% \iffalse meta-comment % Copyright (C) 1989-1992 by Frank Mittelbach. All rights reserved. % This file is part of the doc package. % IMPORTANT NOTICE: % You are not allowed to change this file. You may however copy % this file to a file with a different name and then change the % copy if you obey the restrictions on file changes described in % readme.mz. % You are NOT ALLOWED to distribute this file alone. You are NOT % ALLOWED to take money for the distribution or use of this file % (or a changed version) except for a nominal charge for copying % etc. % You are allowed to distribute this file under the condition that % it is distributed together with all files mentioned in % readme.mz0. % If you receive only some of these files from someone, complain! % However, if these files are distributed by established suppliers % as part of a complete TeX distribution, and the structure of the % distribution would make it difficult to distribute the whole set % of files, *those parties* are allowed to distribute only some of % the files provided that it is made clear that the user will get % a complete distribution-set upon request to that supplier (not % me). Notice that this permission is not granted to the end % user. % For error reports in case of UNCHANGED versions see readme.mz % \fi % ^^A -*-LaTeX-*- % ^^A These shouldn't come out in .ist files, hence the module % ^^A comments, or in the printed version, hence temporary comment % ^^A category for `<' %\catcode`\<=14 %<*style> \def\fileversion{v1.7k} \def\filedate{92/08/24} \def\docdate {92/08/28} % %\catcode`\<=12 % \CheckSum{1985} %% \CharacterTable %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z %% Digits \0\1\2\3\4\5\6\7\8\9 %% Exclamation \! Double quote \" Hash (number) \# %% Dollar \$ Percent \% Ampersand \& %% Acute accent \' Left paren \( Right paren \) %% Asterisk \* Plus \+ Comma \, %% Minus \- Point \. Solidus \/ %% Colon \: Semicolon \; Less than \< %% Equals \= Greater than \> Question mark \? %% Commercial at \@ Left bracket \[ Backslash \\ %% Right bracket \] Circumflex \^ Underscore \_ %% Grave accent \` Left brace \{ Vertical bar \| %% Right brace \} Tilde \~} %\iffalse This is a METACOMMENT % Everything up to the next `\ fi' (without a blank) will % be ignored. This is necessary because `%' may no longer % be a comment mark when this file is read in. % % Style-option `doc' to use with LaTeX v2.09 %% Copyright (C) 1989-1992 Frank Mittelbach, all rights reserved. % Version: Date: Changes: % 1.0a 5.5.88 This is nothing but a collection of tests and % hacks. It is certainly going to be greatly % changed. % Better not to use it! % 1.1a 13.5.88 \theindex and \endtheindex redefined. % 1.1b 15.5.88 \bslash redefined. % \verbatim changed so that `%'s will be ignored. % 1.1c 19.5.88 Partly documented and \@temp... in % \theindex replaced by private commands. % Moreover, \pageshrink incorporated in the % computation of the amount of free space on the % page. % 1.1d 3.6.88 Something goes wrong during the computation of % \pageshrink, therefore a bit of empty space is % inserted by % hand, and some tracing information introduced. % It can't stay like that!! % 1.2a 23.9.88 Documentation of the macros in DOC-format, % i.e. so that this file can document itself. % 1.2b 7.10.88 Change of the index environment. % 1.2c 10.10.88 Further Documentation. % 1.2d 19.10.88 \the before \catcode eliminated. (thanks P. % Breitenlohner) % 1.3a 24.10.88 Scanning of macro names via \scanmacro % introduced to produce index entries. % 1.3b 16.1.89 Scanning of macro names via \scanmacro % improved. % At present only suitable for the makeindex % program % in conjunction with a special style file. % Macro environment in `macro' environment % renamed. % 1.3c 30.1.89 Index environment removed. Will be developed in % other style file. % 1.4a 7.2.89 \SpecialEscapechar added (may change its name). % 1.4b 7.3.89 \SpecialEscapechar reimplemented. % 1.4c 9.3.89 \parts of \short@macro reimplemented because % of some bugs in the macros and the makeindex % program. % Old definition of \b@slash used for \bslash. % \b@slash removed. % 1.4d 10.3.89 English documentation added. % 1.4e 10.3.89 private names for private macros. % \makespecialletters renamed to % \MakePrivateLetters % 1.4f 12.3.89 \short@macro changed (again) % documentation update. % 1.4g 13.3.89 \DoNotIndex macros changed. % 1.4h 13.3.89 \DoNotIndex macros changed to version with % \@elt % 1.4i 15.3.89 documentation update % 1.4j 15.3.89 \printindex inserted % 1.4k 21.3.89 documentation update % \PrintDescribe... and \Describe... added % macro env. + \SpecialIndex changed to accept \ % 1.4l 29.3.89 macro env. changed once more (\macro@ added) to % correct bug introduced in v1.4k % \SpecialUsageIndex and \SpecialEnvIndex added. % 1.4m 3.4.89 \OnlyDescription added, \MakePrivateLetters % changed % 1.4n 10.4.89 \MakePrivateLetters changed back to % \makeatletter. % \ifnot@excluded changed to allow other things % than % macro names in the exclude list (e.g. \abc*) % 1.4o 14.4.89 Documentation update (Brian's correction) % \EnableCrossrefs changed to disable % \DisableCrossrefs % 1.4p 15.4.89 Documentation update \Finale added, % some changes to index.tex % 1.4q 19.4.89 Documentation update \verbatim changed (RmS) % twocolumns env. added index.tex changed. % 1.4r 22.4.89 Changed \macro@ to support \par and % conditionals (might be wrong.) % 1.4s 23.4.89 Getting nearer to the `final' version. % \@sphack ... % placed in several macros. Documentation update. % Tried a \changes macro (somewhere in the middle % of this file by using \glossary (might work!) % 1.4t 24.4.89 Should change to 1.5? Index now uses multicols % added \c@IndexColumns. Other changes forgotten. % Some macro names renamed. % 1.5a 26.4.89 Finally 1.5: changes to \makelabel in macro % env. % 1.5b and higher... are documented with the (undocumented) \changes % feature. % \changes{v1.5f}{89/4/29}{Thanks to Brian who documented the % {\tt\bslash changes} macro feature.} % \changes{v1.5g}{89/5/07}{MacroTopsep now called MacrocodeTopsep and % new MacroTopsep added} % \changes{v1.5h}{89/05/17}{All lines shortened to <72 characters} % \changes{v1.5j}{89/06/09}{Corrections by Ron Whitney added} % \changes{v1.5q}{89/11/03}{`\ldots{}Listing macros renamed to % `\ldots{}Input. Suggested by R. Wonneberger} % \changes{v1.5W}{90/02/05}{Counter codelineno renamed to CodelineNo} % % \hyphenation{make-index} % \DoNotIndex{\@,\@@par,\@beginparpenalty,\@empty} % \DoNotIndex{\@flushglue,\@gobble,\@input} % \DoNotIndex{\@makefnmark,\@makeother,\@maketitle} % \DoNotIndex{\@namedef,\@ne,\@spaces,\@tempa} % \DoNotIndex{\@tempb,\@tempswafalse,\@tempswatrue} % \DoNotIndex{\@thanks,\@thefnmark,\@topnum} % \DoNotIndex{\@@,\@elt,\@forloop,\@fortmp,\@gtempa,\@totalleftmargin} % \DoNotIndex{\",\/,\@ifundefined,\@nil,\@verbatim,\@vobeyspaces} % \DoNotIndex{\|,\~,\ ,\active,\advance,\aftergroup,\begingroup,\bgroup} % \DoNotIndex{\cal,\csname,\def,\documentstyle,\dospecials,\edef} % \DoNotIndex{\egroup} % \DoNotIndex{\else,\endcsname,\endgroup,\endinput,\endtrivlist} % \DoNotIndex{\expandafter,\fi,\fnsymbol,\futurelet,\gdef,\global} % \DoNotIndex{\hbox,\hss,\if,\if@inlabel,\if@tempswa,\if@twocolumn} % \DoNotIndex{\ifcase} % \DoNotIndex{\ifcat,\iffalse,\ifx,\ignorespaces,\index,\input,\item} % \DoNotIndex{\jobname,\kern,\leavevmode,\leftskip,\let,\llap,\lower} % \DoNotIndex{\m@ne,\next,\newpage,\nobreak,\noexpand,\nonfrenchspacing} % \DoNotIndex{\obeylines,\or,\protect,\raggedleft,\rightskip,\rm,\sc} % \DoNotIndex{\setbox,\setcounter,\small,\space,\string,\strut} % \DoNotIndex{\strutbox} % \DoNotIndex{\thefootnote,\thispagestyle,\topmargin,\trivlist,\tt} % \DoNotIndex{\twocolumn,\typeout,\vss,\vtop,\xdef,\z@} % \DoNotIndex{\,,\@bsphack,\@esphack,\@noligs,\@vobeyspaces,\@xverbatim} % \DoNotIndex{\`,\catcode,\end,\escapechar,\frenchspacing,\glossary} % \DoNotIndex{\hangindent,\hfil,\hfill,\hskip,\hspace,\ht,\it,\langle} % \DoNotIndex{\leaders,\long,\makelabel,\marginpar,\markboth,\mathcode} % \DoNotIndex{\mathsurround,\mbox,\newcount,\newdimen,\newskip} % \DoNotIndex{\nopagebreak} % \DoNotIndex{\parfillskip,\parindent,\parskip,\penalty,\raise,\rangle} % \DoNotIndex{\section,\setlength,\TeX,\topsep,\underline,\unskip,\verb} % \DoNotIndex{\vskip,\vspace,\widetilde,\\,\%,\@date,\@defpar} % \DoNotIndex{\[,\{,\},\]} % \DoNotIndex{\count@,\ifnum,\loop,\today,\uppercase,\uccode} % \DoNotIndex{\baselineskip,\begin,\tw@} % \DoNotIndex{\a,\b,\c,\d,\e,\f,\g,\h,\i,\j,\k,\l,\m,\n,\o,\p,\q} % \DoNotIndex{\r,\s,\t,\u,\v,\w,\x,\y,\z,\A,\B,\C,\D,\E,\F,\G,\H} % \DoNotIndex{\I,\J,\K,\L,\M,\N,\O,\P,\Q,\R,\S,\T,\U,\V,\W,\X,\Y,\Z} % \DoNotIndex{\1,\2,\3,\4,\5,\6,\7,\8,\9,\0} % \DoNotIndex{\!,\#,\$,\&,\',\(,\),\+,\.,\:,\;,\<,\=,\>,\?,\_} % \DoNotIndex{\discretionary,\immediate,\makeatletter,\makeatother} % \DoNotIndex{\meaning,\newenvironment,\par,\relax,\renewenvironment} % \DoNotIndex{\repeat,\scriptsize,\selectfont,\the,\undefined} % \DoNotIndex{\arabic,\do,\makeindex,\null,\number,\show,\write,\@ehc} % \DoNotIndex{\@author,\@ehc,\@ifstar,\@sanitize,\@title,\everypar} % \DoNotIndex{\if@minipage,\if@restonecol,\ifeof,\ifmmode} % \DoNotIndex{\lccode,\newtoks,\onecolumn,\openin,\p@,\SelfDocumenting} % \DoNotIndex{\settowidth,\@resetonecoltrue,\@resetonecolfalse,\bf} % \DoNotIndex{\clearpage,\closein,\lowercase,\@inlabelfalse} % \DoNotIndex{\selectfont,\mathcode,\newmathalphabet,\rmdefault} % \DoNotIndex{\bfdefault} % \MakeShortVerb{\"} % \setcounter{StandardModuleDepth}{1} % {\catcode`\p=12 \catcode`\t=12 ^^A hack used later on to print % \gdef\dimenvalue#1pt{$#1$pt}} ^^A a register value with a - sign % \makeatletter ^^A hack so that this can be printed without multicols % \newif \ifmulticols % \ifhave@multicol \multicolstrue \fi % \makeatother % \title{The {\tt doc}--Option\thanks{% % This file has version number \fileversion{} dated \filedate{}. % The documentation was last revised on \docdate. % }} % \author{Frank Mittelbach\thanks{Further commentary added at Royal % Military College of Science by B. Hamilton Kelly; English % translation of parts of the original German commentary % provided by Andrew Mills; fairly substantial additions, % particularly from {\tt newdoc}, and % documentation of post-v1.5q features added at v1.7a by Dave % Love (SERC Daresbury Lab).}\\ % Gutenberg Universit\"at Mainz} % \maketitle % \begin{abstract} % This style option contains the definitions that are necessary to % format the documentation of style files. The style file was % developed in Mainz in cooperation with the Royal Military College % of Science. This is an update which documents various changes % and new features in {\sf doc} and integrates the features of {\sf % newdoc}. % \end{abstract} % \ifmulticols % \addtocontents{toc}{\protect\begin{multicols}{2}} % \fi % {\parskip 0pt ^^A We have to reset \parskip % ^^A (bug in \LaTeX) % \tableofcontents % \changes{v1.7a}{92/02/25}{Miscellaneous small changes to the text} % \ifmulticols % \begin{multicols}{2}[\section*{Preface to version 1.7}] % \else \section*{Preface to version 1.7} \fi % This version of {\tt doc.doc} documents changes which have occurred % since the last published version \cite{art:doc} but which have been % present in distributed versions of {\tt doc.sty} for some time. It % also integrates the (undocumented) features of the distributed {\tt % newdoc.sty}. % The following changes and additions have been made to the user % interface since the published version~\cite{art:doc}. See % \S\ref{sec:interface} for more details. % \begin{description} % \item[Driver mechanism] "\DocInput" is now used in the driver file % to input possibly multiple independent {\tt doc} files and {\tt doc} % no longer has to be the last style option. "\IndexListing" is % replaced by "\IndexInput"; % \item[Indexing] is controlled by "\PageIndex" and % "\CodelineIndex", one of which must be specified to produce an % index---there is no longer a "\makeindex" in the default % "\DocstyleParms"; % \item[The {\tt macro} environment] now takes as argument the macro % name {\em with\/} the backslash; % \item[Verbatim text] Newlines are now forbidden inside "\verb" and % commands "\MakeShortVerb" and "\DeleteShortVerb" are provided for % verbatim shorthand; % \item[{\tt \bslash par}] can now be used in "\DoNotIndex"; % \item[Checksum/character table support] for ensuring the % integrity of distributions is added; % \item[{\tt \bslash printindex}] becomes "\PrintIndex"; % \item[{\tt multicol.sty}] is no longer necessary to use {\tt doc} or % print the documentation (although it is recommended); % \item[`Docstrip' modules] are recognised and formatted specially. % \end{description} % As well as adding some completely new stuff, % the opportunity has been taken to add some commentary to the code % formerly in {\tt newdoc.sty} and that added after version 1.5k of % {\tt doc.sty}. Since (as noted in the sections concerned) this % commentary wasn't written by Frank Mittelbach but the code was, it is % probably {\em not\/} true in this case that ``if the code and % comments disagree both are probably wrong''! % \subsection*{Bugs} % There are some known bugs in this version: % \begin{itemize} % \item The `General changes' glossary entry would come out after % macro names with a leading "!" and possibly a leading \verb+"+; % \item If you have an old version of {\sf makeindex} long "\changes" % entries will come out strangely and you may find the section % header amalgamated with the first changes entry. Try to get an % up-to-date one (see p.~\pageref{makeindex:version}); % \item Because the accompanying {\sf makeindex} style files support % the inconsistent attribute specifications of older and newer % versions {\sf makeindex} always complains about three `unknown % specifier's when sorting the index and changes entries. % \item If "\MakeShortVerb" and "\DeleteShortVerb" are used with % single character arguments, e.g., "{|}" instead of "{\|}" chaos % may happen. % \end{itemize} % (Some `features' are documented below.) % \subsection*{Wish list} % \begin{itemize} % \item Hooks to allow "\DescribeMacro" and "\DescribeEnv" to write % out to a special file information about the style's `exported' % definitions which they describe. This could subsequently be % included in the {\tt docstrip}ped {\tt .sty} file in a suitable form % for use by smart editors in command completion, spelling checking % etc., based on the style options of a document. This would need % agreement on a `suitable form'. % \item Indexing of the modules used in {\tt docstrip}'s "%<" % directives. I'm not sure how to index directives containing % module combinations; % \item Writing out bibliographic information about the style; % \item Allow turning off use of the special font for, say, the next % guarded block. % \end{itemize} % \ifmulticols % \end{multicols} % \begin{multicols}{2}[\medskip \rule{\textwidth}{.3pt} % \section{Introduction}] % \else % \section{Introduction} % \fi % The \TeX{} macros which are described here allow definitions and % documentation to be held in one and the same file. This has the % advantage that normally very complicated instructions are made % simpler to understand by comments inside the definition. In addition % to this, updates are easier and only one source file needs to be % changed. On the other hand, because of this, the style files are % considerably longer: thus \TeX{} takes longer to load them. If this % is a problem, there is an easy remedy: one needs only to run the % {\tt docstrip.tex} program that removes nearly all lines that begin % with a % percent sign. % The idea of integrated documentation was born with the development % of the \TeX{} program; it was crystallized in Pascal with the \Web{} % system. The advantages of this method are plain to see (it's easy % to make comparisons \cite{art:Knuthliterat}). Since this % development, systems similar to \Web{} have been developed for other % programming languages. But for one of the most complicated % programming languages (\TeX) the documentation has however been % neglected. The \TeX{} world seems to be divided between:--- % \begin{itemize} \item a couple of ``wizards'', who produce many % lines of completely unreadable code ``off the cuff'', and \item many % users who are amazed that it works just how they want it to do. Or % rather, who despair that certain macros refuse to do what is % expected of them.\end{itemize} % I do not think that the \Web{} system is {\em the\/} reference work; % on the contrary, it is a prototype which suffices for the % development of programs within the \TeX{} world. It is sufficient, % but not totally sufficient.\footnote{I know that this will be seen % differently by a few people, but this product should not be seen as % the finished product, at least as far as applications concerning % \TeX{} are concerned. The long-standing debate over `multiple % change files' shows this well.} As a result of \Web, new programming % perspectives have been demonstrated; unfortunately, though, they % haven't been developed further for other programming languages. % The method of documentation of \TeX{} macros which I have introduced % here should also only be taken as a first sketch. It is designed % explicitly to run under \LaTeX{} alone. Not because I was of the % opinion that this was the best starting point, but because from this % starting point it was the quickest to develop.\footnote{This % argument is a bad one, however, it is all too often trotted out.} As % a result of this design decision, I had to move away from the % concept of modularization; this was certainly a step backward. % I would be happy if this article could spark off discussion over % \TeX\ documentation. I can only advise anyone who thinks that they % can cope without documentation to ``Stop Time'' until he or she % completely understands the \AmSTeX{} source code. % \subsection{Using the {\sf doc} style option} % Just like any other option, invoke it by including it amongst the % style options in the optional parameter list for the % \verb+\documentstyle+ command. {\sf Doc}'s use of % \verb+\reversemarginpars+ may make it incompatible with some style % options. % \changes{v1.7a}{92/02/25}{Altered usage info} % \ifmulticols\end{multicols}\fi % \section{The User Interface}\label{sec:interface} % \subsection{The driver file} % If one is going to document a set of macros with the {\tt doc} % option one has to prepare a special driver file which produces the % formatted document. This driver file has the following % characteristics: % \noindent \verb+\documentstyle[+\meta{options}]^^A % \verb+{+\meta{document-style}\verb+}+\\[3pt] % \hspace*{10pt}\meta{preamble}\\[3pt] % \verb+\begin{document}+\\[3pt] % \hspace*{10pt}\meta{special input commands}\\[3pt] % \verb+\end{document}+ % The list of \meta{options} must contain the {\tt doc} option but it % is not necessary any longer to put this option on the end of the % list. % The \meta{document-style} might be any document style, I normally % use {\tt article}. % In the \meta{preamble} one should place declarations which % manipulate the behavior of the {\tt doc} option like % \verb+\DisableCrossrefs+ or \verb+\OnlyDescription+. % \DescribeMacro\DocInput \DescribeMacro\IndexInput % Finally the \meta{special input commands} part should contain one or % more \verb+\DocInput+\meta{file name} and/or % \verb+\IndexInput+\meta{file name} commands. The % \verb+\DocInput+ command is used for files prepared for the {\tt % doc} option whereas \verb+\IndexInput+ can be used for all kinds of % macro files. See page \pageref{..Input} for more details of % "\IndexInput". Multiple "\DocInput"s can be used with a % number of included files which are each self-contained % self-documenting styles---for instance, each containing % "\maketitle". % As an example, the driver file for the {\tt doc} option itself is % derived from the following text. This is meant to be extracted by % the {\tt docstrip} program which will remove the leading "<+driver>" % indicating the `module'; the line numbers are added by {\tt % doc}'s formatting. % \changes{v1.7a}{92/03/06}{Added docstrip-derivable driver file as % example.} % \changes{v1.7c}{92/04/01}{Expurgated ltugboat.sty from driver.} % \begin{macrocode} %<+driver>\documentstyle[doc]{article} %<+driver>% dimensions from ltugboat.sty: %<+driver>\setlength\textwidth{31pc} \setlength\textheight{54pc} %<+driver>\setlength{\parindent}{0pt} %<+driver>\setlength{\parskip}{2pt plus 1pt minus 1pt} %<+driver>\setlength{\oddsidemargin}{8pc} %<+driver>\setlength{\marginparwidth}{8pc} %<+driver>\setlength{\topmargin}{-2.5pc} %<+driver>\setlength{\headsep}{20pt} %<+driver>\setlength{\columnsep}{1.5pc} %<+driver>\setlength{\columnwidth}{18.75pc} %<+driver>\EnableCrossrefs %<+driver>%\DisableCrossrefs % Say \DisableCrossrefs if index is ready %<+driver>\RecordChanges % Gather update information %<+driver>\CodelineIndex % Index code by line number %<+driver>%\OnlyDescription % comment out for implementation details %<+driver>%\OldMakeindex % use if your MakeIndex is pre-v2.9 %<+driver>\begin{document} %<+driver> \DocInput{doc.doc} %<+driver>\end{document} % \end{macrocode} %^^A As an example this is the driver file for the {\tt doc} option %^^A itself: %^^A\begin{verbatim} %^^A\documentstyle[ltugboat,doc]{article} %^^A % \DisableCrossrefs % Say \DisableCrossrefs if the index %^^A % is ready. %^^A \RecordChanges % Gather update-information %^^A % \OnlyDescription % Remove the comment char if you only want %^^A % the description %^^A\SelfDocumenting % Tugbot style macro (for doc) %^^A\begin{document} %^^A \DocInput{doc.doc} %^^A\end{document} %^^A\end{verbatim} % \changes{v1.7a}{92/02/25}{Note on avoiding driver file} % \subsection{Avoiding using a driver file} % It is possible to dispense with a driver file at the expense of some % flexibility using the following trick.\footnote{Due to David % Carlisle, Manchester University.} Before the documentation part of % the file starts, include (without leading "%"s!)\ something like % \begin{verbatim} %\ifcat a\noexpand @\let\next\relax\else\def\next{% % \documentstyle[doc]{article}\MakePercentIgnore}\fi\next %\end{verbatim} % with any necessary extra style options included, of course. Then % the file can either be used directly as a style file as normal or % have the documentation printed simply by using % "latex"~\meta{filename}. You can also arrange to have this process % ask questions about whether to format only the usage section, for % instance. % \subsection{General conventions} % A \TeX{} file prepared to be used with the `doc' style option % consists of `documentation parts' intermixed with `definition % parts'. % Every line of a `documentation part' starts with a percent sign % (\verb+%+) in column one. It may contain arbitrary \TeX{} or % \LaTeX{} commands except that the character `\verb+%+' cannot be % used as a comment character. % \SortIndex{\string^\string^A}{\string\verb\verbatimchar % \string^\string^A\verbatimchar \encapchar usage} To allow user % comments, the \verb+^^A+ character is defined as a comment character % later on. Such `metacomments' may be also be included simply by % surrounding them with "\iffalse" \ldots~"\fi". % All other parts of the file are called `definition parts'. They % contain fractions of the macros described in the `documentation % parts'. % If the file is used to define new macros (e.g.\ as a style file in % the \verb+\documentstyle+ macro), the `documentation parts' are % bypassed at high speed and the macro definitions are pasted % together, even if they are split into several `definition parts'. % \DescribeEnv{macrocode} % On the other hand, if the documentation of these macros is to be % produced, the `definition parts' should be typeset verbatim. To % achieve this, these parts are surrounded by the {\sf macrocode} % environment. % More exactly: before a `definition part' there should be a line % containing\\ % \hspace*{\MacroIndent}\verb*+% \begin{macrocode}+\\ % and after this part a line\\ % \hspace*{\MacroIndent}\verb*+% \end{macrocode}+\\ % There must be {\em exactly\/} four spaces between the \verb+%+ % and \verb+\end{macrocode}+ --- \TeX{} is looking for this string % and not for the macro while processing a `definition part'. % Inside a `definition part' all \TeX{} commands are allowed; even the % percent sign could be used to suppress unwanted spaces etc. % \DescribeEnv{macrocode*} % Instead of the {\sf macrocode} environment one can also use the {\sf % macrocode$*$} environment which produces the same results except % that spaces are printed as \nopagebreak\verb*+ + characters. % \subsection{Describing the usage of new macros} % \DescribeMacro\DescribeMacro % When you describe a new macro you may use \verb+\DescribeMacro+ to % indicate that at this point the usage of a specific macro is % explained. It takes one argument which will be printed in the margin % and also produces a special index entry. For example, I used % \verb+\DescribeMacro{\DescribeMacro}+ to make clear that this is the % point where the usage of \verb+\DescribeMacro+ is explained. % \DescribeMacro\DescribeEnv % An analogous macro \verb+\DescribeEnv+ should be used to indicate % that a \LaTeX{} environment is explained. It will produce a somewhat % different index entry. Below I used \verb+\DescribeEnv{verbatim}+. % \DescribeEnv{verbatim} % It is often a good idea to include examples of the usage of new macros % in the text. Because of the \verb+%+ sign in the first column of every % row, the {\sf verbatim} environment is slightly altered to suppress % those % characters.\footnote{These macros were written by Rainer % Sch\"opf~\cite{art:verbatim}. He also % provided a new {\sf verbatim} environment which % can be used inside of other macros.} % \DescribeEnv{verbatim*} % The {\sf verbatim$*$} environment is changed in the same way. % \changes{v1.7a}{92/02/26}{Documented `verb change.} % \DescribeMacro\verb % The "\verb" command is re-implemented to give an error report if a % newline appears in its argument. % The {\sf verbatim} and {\sf verbatim$*$} environments set text in % the style defined by "\MacroFont"~(\S\ref{sec:macrofont}). % \subsection{Describing the definition of new macros} % \DescribeEnv{macro} % To describe the definition of a new macro we use the {\sf macro} % environment. It has one argument: the name of the new % macro.\footnote{This is a change to the style design I described in % ^^A \TUB ^^A removed in case ltugboat.sty not used % {\sl TUGboat\/}\ 10\#1 (Jan.~89). We finally decided % that it would % be better to use the macro name {\em with\/} the % backslash as an argument.} % This argument is also used to print the name in the margin and to % produce an index entry. % Actually the index entries for usage and definition are different to % allow an easy reference. % This environment might be nested. In this case the % labels in the margin are placed under each other. % \changes{v1.7a}{92/02/26}{Note on need for some text in macro env.} % There should be some text---even if it's just an empty % "\mbox{}"---in this environment before "\begin{macrocode}" or the % marginal label won't print in the right place. % \DescribeMacro\MacrocodeTopsep % \DescribeMacro\MacroTopsep % There also exist four style parameters: \verb+\MacrocodeTopsep+ and % \verb+\MacroTopsep+ are used to control the vertical spacing above % and below the {\sf macrocode} and the {\sf macro} % \DescribeMacro\MacroIndent % environment, \verb+\MacroIndent+ is used to indent the lines of code % and % \DescribeMacro\MacroFont \label{sec:macrofont} % \verb+\MacroFont+ holds the font and a possible size change command % for the code lines, the "verbatim"["*"] environment and the macro % names printed in the margin. If you want % to change their default values in a % style file (like {\tt ltugboat.sty}) use the \verb+\DocstyleParms+ % command described below. % \subsection{Formatting the margins} % \DescribeMacro\PrintDescribeMacro % \DescribeMacro\PrintDescribeEnv % \DescribeMacro\PrintMacroName % As mentioned earlier, some macros and the {\sf macro} environment % print their arguments in the margin. This is actually done by three % macros which are user % definable.\footnote{You may place the changed definitions in a % separate style % file or at the beginning of the documentation % file. % For example, if you don't like any names in the % margin % but want a fine index you can simply % {\tt \bslash let} % these macros equal {\tt \bslash @gobble}. % The doc style option won't redefine any existing % definitions of these macros.} % They are named \verb+\PrintDescribeMacro+, \verb+\PrintDescribeEnv+ % and \verb+\PrintMacroName+ (called by the {\sf macro} environment). % \subsection{Using a special escape character} % \DescribeMacro\SpecialEscapechar % If one defines complicated macros it is sometimes necessary to % introduce a new escape character because the `\verb+\+' has got a % special \verb+\catcode+. In this case one can use % \verb+\SpecialEscapechar+ to indicate which character is actually % used to play the r\^ole of the `\verb+\+'. A scheme like this is % needed because the {\sf macrocode} environment and its counterpart % {\sf macrocode$*$} produce an index entry for every occurrence of a % macro name. They would be very confused if you didn't tell them that % you'd changed \verb+\catcode+$\,$s. The argument to % \verb+\SpecialEscapechar+ is a single-letter control sequence, that % is, one has to use \verb+\|+ for example to denote that `\verb+|+' % is used as an escape character. \verb+\SpecialEscapechar+ only % changes the behavior of the next {\sf macrocode} or {\sf % macrocode$*$} environment. % The actual index entries created will all be printed with \verb+\+ % rather than \verb+|+, but this probably reflects their usage, if not % their definition, and anyway must be preferable to not having any % entry at all. The entries {\em could\/} be formatted appropriately, % but the effort is hardly worth it, and the resulting index might be % more confusing (it would certainly be longer!). % \subsection{Cross-referencing all macros used} % \DescribeMacro\DisableCrossrefs % \DescribeMacro\EnableCrossrefs % As already mentioned, every new macro name used within a {\sf % macrocode} or {\sf macrocode$*$} environment will produce an index % entry. In this way one can easily find out where a specific macro is % used. Since \TeX{} is considerably slower when it has to produce % such a bulk of index entries one can turn off this feature by using % \verb+\DisableCrossrefs+ in the driver file. To turn it on again % just use % \verb+\EnableCrossrefs+.\footnote{Actually, % {\tt\bslash EnableCrossrefs} % changes things more drastically; any following % {\tt\bslash DisableCrossrefs} % which might be present in the source will be ignored.} % \DescribeMacro\DoNotIndex % But also finer control is provided. The \verb+\DoNotIndex+ macro % takes a list of macro names separated by commas. Those names won't % show up in the index. You might use several \verb+\DoNotIndex+ % commands: their lists will be concatenated. In this article I used % \verb+\DoNotIndex+ for % all macros which are already defined in \LaTeX. % All three above declarations are local to the current group. % Production (or not) of the index (via the "\makeindex" commend) is % controlled by using or omitting the following declarations in the % driver file preamble; if neither is used, no index is produced. % \DescribeMacro\PageIndex Using "\PageIndex" makes all index % entries refer to their page number; with % \DescribeMacro\CodelineIndex "\CodelineIndex", index entries % produced by "\DescribeMacro" and "\DescribeEnv" refer to page number % but those produced by the {\sf macro} environment refer to the % code lines, which will be numbered automatically.\footnote{The line % number is actually that of the first line of the first {\sf % macrocode} environment in the {\sf macro} environment.} % \DescribeMacro\theCodelineNo % The style of this numbering can be controlled by defining the macro % "\theCodelineNo". Its default definition is to use scriptsize % arabic numerals; a user-supplied definition won't be overwritten. % \subsection{Producing the actual index entries} % Several of the aforementioned macros will produce some sort of index % entries. These entries have to be sorted by an external % program---the current implementation assumes that the {\sf % makeindex} program by Chen~\cite{art:Chen} is used. % But this isn't built in: one has only to redefine some of the % following macros to be able to use any other index program. All % macros which are installation % dependent are defined in such a way that they won't overwrite a % previous definition. Therefore it is safe to put the changed % versions in a style file which might be read in before the doc style % option. % To allow the user to change the specific characters recognized by % his or her index program all characters which have special meaning % in the {\sf makeindex} program are given symbolic % names.\footnote{I don't know if there exists a program which needs % more command characters, but I hope not.} % However, all characters used should be of \verb+\catcode+ other than % `letter' (11). % \DescribeMacro{\actualchar} % The \verb+\actualchar+ is used to separate the `key' and the actual % index entry. % \DescribeMacro{\quotechar} % The \verb+\quotechar+ is used before a special index program % character to suppress its special meaning. % \DescribeMacro{\encapchar} % The \verb+\encapchar+ separates the indexing information from a % letter string which {\sf makeindex} uses as a \TeX{} command to % format the page number associated with a special entry. It is used % in this style to apply the \verb+\main+ and the \verb+\usage+ % commands. % \DescribeMacro{\levelchar} % Additionally \verb+\levelchar+ is used to separate `item', % `subitem' and `subsubitem' entries. % It is a good idea to stick to these symbolic names even if you know % which index program is used. In this way your files will be % portable. % \DescribeMacro\SpecialMainIndex % To produce a main index entry for a macro the % \verb+\SpecialMainIndex+ macro\footnote{This macro is called by the % {\sf macro} environment.} may be used. It is called `special' % because it has to print its argument verbatim. % \DescribeMacro\SpecialIndex % If you want a normal index entry for a macro name % \verb+\SpecialIndex+ might be used.\footnote{This macro is called % within the {\sf macrocode} environment when encountering a macro % name.} % \DescribeMacro\SpecialUsageIndex % \DescribeMacro\SpecialEnvIndex % To index the usage of a macro or an environment % \verb+\SpecialUsageIndex+ and \verb+\SpecialEnvIndex+ may be used. % \DescribeMacro\SortIndex % Additionally a \verb+\SortIndex+ command is provided. It takes two % arguments---the sort key and the actual index entry. % All these macros are normally used by other macros; you will need % them only in an emergency. % \DescribeMacro\verbatimchar % But there is one characteristic worth mentioning: all macro names in % the index are typeset with the \verb+\verb*+ command. Therefore one % special character is needed to act as a delimiter for this command. % To allow a change in this respect, again this character is % referenced indirectly, by the macro \verb+\verbatimchar+. It expands % by default to \verb?+? but if your code lines contain macros with % `{\tt +}' characters in their names (e.g.\ when you use \verb?\+?) % you will end up with an index entry containing \verb?\verb+\++? % which will be typeset as `\verb+\++' and not as `\verb?\+?'. In this % case you should redefine \verb+\verbatimchar+ globally or locally to % overcome this problem. % \DescribeMacro\* % We also provide a \verb+\*+ macro. This is intended to be used for % index entries like % \begin{quote} % index entries \\ % \hspace*{30pt} Special macros for \* % \end{quote} % Such an entry might be produced with the line: %\begin{verbatim} % \index{index entries\levelchar Special macros for \*} %\end{verbatim} % \DescribeMacro\OldMakeindex % Versions of {\sf makeindex} prior to 2.9 had some bugs affecting % {\sf doc}. One of these, % pertaining to the "%" character doesn't have a work-around % appropriate for versions with and without the % bug.\label{makeindex:version} If % you have an old version, invoke "\OldMakeindex" in a % style file or the driver file to prevent problems with index entries % such as "\%", although you'll probably normally want to turn off % indexing of "\%" anyway. Try to get an up-to-date {\sf makeindex} % from one of the \TeX{} repositories. % \subsection{Setting the index entries} % \changes{v1.7a}{92/03/11}{Usage note on gind.ist.} % After the first formatting pass through the {\tt .doc} file you need % to sort the index entries written to the {\tt .idx} file using {\sf % makeindex} or your favourite alternative. You need a suitable style % file for {\sf makeindex} (specified by the {\tt -s} switch). A % suitable one is supplied with {\sf doc}, called {\tt gind.ist}. % \DescribeMacro\PrintIndex % To read in and print the sorted index, just put the % \verb+\PrintIndex+ command as the last (commented-out, and thus % executed during the documentation pass through the file) command % in your style file. Precede it by any bibliography commands % necessary for your citations. % Alternatively, it may be more convenient to put all such calls % amongst the arguments of the \verb+\StopEventually+ macro, in % which case a \verb+\Finale+ command should appear at the end of % your file. % \DescribeEnv{theindex} % Contrary to standard \LaTeX, the index is typeset in three columns % by default. This is controlled by the \LaTeX{} counter `{\sf % IndexColumns}' and can therefore be changed with a % \verb+\setcounter+ declaration. Additionally one doesn't want to % start a new page unnecessarily. Therefore the {\sf theindex} % environment is redefined. % \DescribeMacro\IndexMin % When the {\sf theindex} environment starts it will measure how much % space is left on the current page. If this is more than % \verb+\IndexMin+ then the index will start on this page. Otherwise % \verb+\newpage+ is called. % Then a short introduction about the meaning of several index entries % is typeset (still in onecolumn mode). Afterwards the actual index % entries follow in multi-column mode. % \DescribeMacro\IndexPrologue % You can change this prologue with the help of the % \verb+\IndexPrologue+ macro. Actually the section heading is also % produced in this way, so you'd better write something like: % \begin{verbatim} % \IndexPrologue{\section*{Index} The index entries underlined ...} %\end{verbatim} % When the {\sf theindex} environment is finished the last page will % be reformatted to produce balanced columns. This improves the layout % and allows the next article to start on the same page. % \DescribeMacro\IndexParms % Formatting of the index columns (values for \verb+\columnssep+ % etc.)\ is controlled by the \verb+\IndexParms+ macro. It assigns the % following values: % \SpecialUsageIndex{\parindent}\SpecialUsageIndex{\columnsep}^^A % \SpecialUsageIndex{\parskip}\SpecialUsageIndex{\rightskip}^^A % \SpecialUsageIndex{\mathsurround}\SpecialUsageIndex{\parfillskip} % \begin{center} % \begin{tabular}{l@{\,=\,}ll@{\,=\,}l} % \verb+\parindent+ & \IndexParms \the\parindent & % \verb+\columnsep+ & \IndexParms \the\columnsep \\ % \verb+\parskip+ & \IndexParms \the\parskip & % \verb+\rightskip+ & \IndexParms % \expandafter\dimenvalue\the\rightskip \\ % \verb+\mathsurround+ & \IndexParms \the\mathsurround & % \verb+\parfillskip+ & \IndexParms % \expandafter\dimenvalue\the\parfillskip % \end{tabular} % \end{center} % \DescribeMacro{\@idxitem} % Additionally it defines \verb+\@idxitem+ (which will be used when an % \verb+\item+ command is encountered) and selects \verb+\small+ size. % If you want to change any of these values you have to define them % all. % \DescribeMacro\main % \DescribeMacro\usage % The page numbers for main index entries are encapsulated by the % \verb+\main+ macro (underlining its argument) and the numbers % denoting the description are encapsulated by the \verb+\usage+ macro % (which produces {\em italics}). As usual these commands are user % definable. % \subsection{Changing the default values of style parameters} % \DescribeMacro\DocstyleParms % If you want to overwrite some default settings made by the {\tt doc} % style, you can either put your declarations in the driver file (that % is after {\tt doc.sty} is read in) or use a separate style file for % doing this work. In the latter case you can define the macro % \verb+\DocstyleParms+ to contain all assignments. This % indirect approach is necessary if your style file might be read % before the {\tt doc.sty}, when some of the registers are not % allocated. Its default definition is null. % The doc style option currently assigns values to the following % registers: % \SpecialUsageIndex{\IndexMin}\SpecialUsageIndex{\MacrocodeTopsep}^^A % \SpecialUsageIndex{\MacroTopsep}^^A % \SpecialUsageIndex{\MacroIndent}\SpecialUsageIndex{\marginparpush}^^A % \SpecialUsageIndex{\marginparwidth}\SpecialUsageIndex{\tolerance} % \begin{center} % \begin{tabular}{l@{\,=\,}ll@{\,=\,}l} % \verb+\IndexMin+ & \the\IndexMin & % \verb+\MacroTopsep+ & \the\MacroTopsep \\ % \verb+\marginparwidth+& \the\marginparwidth & % \verb+\MacroIndent+ & \the\MacroIndent \\ % \verb+\marginparpush+ & \the\marginparpush & % \verb+\MacrocodeTopsep+ & \the\MacrocodeTopsep \\ % \verb+\tolerance+ & \the\tolerance % \end{tabular} % \end{center} % \subsection{Additional bells and whistles} % We provide macros for logos such as \Web, \AmSTeX, \BibTeX, % \SliTeX{} and \PlainTeX. Just type \verb+\Web+, \verb+\AmSTeX+, % \verb+\BibTeX+, \verb+\SliTeX+ or \verb+\PlainTeX+, respectively. % \LaTeX{} and \TeX{} are already defined in {\tt latex.tex}. % \DescribeMacro\meta % Another useful macro is \verb+\meta+ which has one argument and % produces something like \meta{dimen parameter}. % \DescribeMacro\OnlyDescription % \DescribeMacro\StopEventually % You can use the \verb+\OnlyDescription+ declaration in the driver % file to suppress the last part of your document (which presumably % exhibits the code). To make this work % you have to place the command \verb+\StopEventually+ at a suitable % point in your file. This macro has one argument in which you put % all information you want to see printed if your document ends at % this point (for example a bibliography which is normally printed at % the very end). When the \verb+\OnlyDescription+ declaration is % missing the \verb+\StopEventually+ % \DescribeMacro\Finale % macro saves its argument in a macro called \verb+\Finale+ which can % afterwards be used to get things back (usually at the very end). % Such a scheme makes changes in two places unnecessary. % Thus you can use this feature to produce a local guide for the % \TeX{} users which describes only the usage of macros (most of them % won't be interested in your definitions anyway). For the same % reason the \verb+\maketitle+ % \DescribeMacro\maketitle % command is slightly changed to allow multiple titles in one % document. So you can make one driver file reading in several % articles at once. % \DescribeMacro{\ps@titlepage} % To avoid an unwanted {\sf pagestyle} on the title page the % \verb+\maketitle+ command issues a \verb+\thispagestyle{titlepage}+ % declaration which produces a {\sf plain} page if the {\sf titlepage} % page style is undefined. This allows style files like {\sf % ltugboat.sty} to define their own page styles for title pages. % \DescribeMacro\IndexInput \label{..Input} % Last but not least I defined an \verb+\IndexInput+ macro which % takes a file name as an argument and produces a verbatim listing of % the file, indexing every command as it goes along. This might be % handy, if you want to learn something about macros without enough % documentation. I used this feature to cross-reference {\tt % latex.tex} getting a verbatim copy with about 15 pages % index.\footnote{It took quit a long time and the resulting {\tt .idx} % file was longer than the {\tt .dvi} file. % Actually too long to be handled by the {\sf makeindex} % program directly (on our MicroVAX) but the final result % was worth the trouble.} % \DescribeMacro\changes % To maintain a change history within the file, the \verb+\changes+ % command may be placed amongst the description part of the changed % code. It takes three arguments, thus: % \begin{quote} % \verb+\changes{+\meta{version}\verb+}{+\meta{date}\verb+}{+^^A % \meta{text}\verb+}+ % \end{quote} % The changes may be used to produce an auxiliary file (\LaTeX's % \verb+\glossary+ mechanism is used for this) which may be printed % after suitable formatting. The \verb+\changes+ macro encloses the % \meta{date} in parentheses and appends the \meta{text} to form the % printed entry in such a change history; because old % versions\footnote{Before 2.6.} of the {\sf makeindex} % program limit such fields to 64 characters, care should be taken % not to exceed this limit when describing the change. When % referring to macros in change descriptions it is conventional to use % "`"\meta{macroname} rather than attempting to format it properly and % using up valuable characters in the entry with old {\sf makeindex} % versions. % \changes{v1.7a}{92/02/26}{Description of `RecordChanges etc. added % to interface section.} % \DescribeMacro\RecordChanges % To cause the change information to be written out, include % "\RecordChanges" in the driver file. % \DescribeMacro\PrintChanges % To read in and print the sorted change history (in two columns), % just put the \verb+\PrintChanges+ command as the last % (commented-out, and thus executed during the documentation pass % through the file) command in your style file. Alternatively, this % command may form one of the arguments of the \verb+\StopEventually+ % command, although a change history is probably {\em not\/} required % if only the description is being printed. % The command assumes that {\sf makeindex} or some other program % has processed the {\tt.glo} file to generate a sorted {\tt.gls} file. % You need a special {\sf makeindex} style file; a suitable one is % supplied with {\sf doc}, called {\tt gglo.ist}. % \DescribeMacro\GlossaryMin \DescribeMacro\GlossaryPrologue % \DescribeMacro\GlossaryParms % The "\GlossaryMin", "\GlossaryPrologue" and "\GlossaryParms" macros % are analagous to the "\Index"\ldots\ versions. (The \LaTeX{} % `glossary' mechanism is used for the change entries.) % \label{sec:checksum} % \DescribeMacro\CharacterTable % \DescribeMacro\CheckSum % To overcome some of the problems of sending files over the networks % we developed two macros which should detect corrupted files. If one % places the lines % \begin{verbatim} %%% \CharacterTable %%% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z %%% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z %%% Digits \0\1\2\3\4\5\6\7\8\9 %%% Exclamation \! Double quote \" Hash (number) \# %%% Dollar \$ Percent \% Ampersand \& %%% Acute accent \' Left paren \( Right paren \) %%% Asterisk \* Plus \+ Comma \, %%% Minus \- Point \. Solidus \/ %%% Colon \: Semicolon \; Less than \< %%% Equals \= Greater than \> Question mark \? %%% Commercial at \@ Left bracket \[ Backslash \\ %%% Right bracket \] Circumflex \^ Underscore \_ %%% Grave accent \` Left brace \{ Vertical bar \| %%% Right brace \} Tilde \~} %\end{verbatim} % at the beginning of the file then character translation failures % will be detected, provided of course, that the used {\tt doc} option % has a correct default table. The percent signs\footnote{There are % two percent signs in each line. This has the effect that these lines % are not removed by the {\tt docstrip.tex} program.} at the beginning % of the lines should be typed in, since only the {\tt doc} option % should look at this command. % Another problem of mailing files is possible truncation. To % detect these sort of errors we provide a \verb+\CheckSum+ macro. % The check-sum of a file is simply the number of backslashes in the % code, i.e.\ all lines between the {\sf macrocode} environments. But % don't be afraid: you don't have count the code-lines yourself; this % is done by the {\tt doc} style option for you. You simply have to % use the \verb+\StopEventually+ (which starts looking for backslashes) % and the \verb+\Finale+ command. The latter will inform you either % that your file has no check-sum (telling you the right number) or % that your number is incorrect (this time telling you both the % correct and the incorrect one). Then you go to the top of your file % inserting the line % \begin{quote} % \verb+%% \CheckSum{+\meta{number}\verb+}+ % \end{quote} % and that's all. If you precede it only with one percent then the % line will not show up in {\tt docstrip} versions of the file. % You should do so whenever you are using conditional code (see % {\tt docstrip} documentation) since then the check-sum will not % reflect the number of backslashes in the stripped of versions. % \DescribeMacro\bslash % From time to time, it is necessary to print a \verb+\+ without % being able to use the \verb+\verb+ command because the % \verb+\catcode+$\,$s of the symbols are already firmly % established. In this instance we can use the command % \verb+\bslash+ presupposing, of course, that the actual font in % use at this point contains a `backslash' as a symbol. Note that % this definition of \verb+\bslash+ is expandable; it inserts a % $"\"_{12}$. This means that you have to \verb+\protect+ % it if it is used in `moving arguments'. % \DescribeMacro\MakePrivateLetters % \changes{v1.7a}{92/02/26}{Documented `MakePrivateLetters in % interface section}^^A % If your macros "\catcode" anything other than "@" to `letter', you % should redefine "\MakePrivateLetters" so that it also makes the % relevant characters `letters' for the benefit of the indexing. The % default definition is just "\makeatletter". % \DescribeMacro\MakeShortVerb \DescribeMacro\DeleteShortVerb % It is awkward to have to type, say, "\verb+"\ldots"+" continually % when quoting verbatim bits (like macro names) in the text, so an % abbreviation mechanism is provided. Pick a character % \meta{c}---one which normally has catcode `other' unless you have % very good reason not to---which % you don't envisage using in the text, or not using often. (I like % \verb+"+, but you may prefer "|" if you have \verb+"+ active to do % umlauts, for instance.) Then if you say % "\MakeShortVerb{\"\meta{c}"}" you can subsequently use % \meta{c}\meta{text}\meta{c} as the equivalent of % "\verb"\meta{c}\meta{text}\meta{c}. Use % "\DeleteShortVerb{\"\meta{c}"}" if you subsequently % want \meta{c} to revert to its previous meaning---you can % always turn it on again after the unusual section. The `short verb' % commands make global changes. The abbreviated "\verb" may not % appear in the argument of another command just like "\verb". % However the `short verb' character may be used freely in the {\sf % verbatim} and {\sf macrocode} environments without ill effect. % "\DeleteShortVerb" is silently ignored if its argument does not % currently represent a short verb character. Both commands type a % message to tell you the meaning of the character is being changed. % \DescribeMacro\DontCheckModules \DescribeMacro\CheckModules % \DescribeMacro\Module \DescribeMacro\AltMacroFont % The `module' directives of the {\sf docstrip} system % \cite{art:docstrip} are normally % recognised and invoke special formatting. This can be turned on and % off in the {\tt .doc} file or the driver file using "\CheckModules" % and "\DontCheckModules". If checking for module directives is on % (the default) then code in the scope of the directives is set as % determined by the hook "\AltMacroFont", which gives {\small\tt\it % small italic type\-writer\/} by default in the New Font % Selection Scheme but just ordinary {\small\tt small type\-writer} in % the old one, where a font such as italic typewriter can't be used % portably (plug for NFSS); you will need to override % this if you don't have the italic typewriter font available. % Code is in such a scope if it's on a line beginning with "%<" or is % between lines starting with "%<*"\meta{name list}">" and % "%". The directive is formatted by the macro % "\Module" whose single argument is the text of the % directive between, but not including, the angle brackets; this macro % may be re-defined in the driver or style file and by default % produces results like \Module{+foo|bar} with no following space. % \DescribeMacro{StandardModuleDepth} Sometimes (as in this file) the % whole code is surrounded by modules to produce several files from a % single source. In this case it is clearly not appropriate to format % all code lines in a special "\AltMacroFont". For this reason a % counter "StandardModuleDepth" is provided which defines the level of % module nesting which is still supposed to be formatted in % "\MacroFont" rather then "\AltMacroFont". The default setting is % "0", for this documentation it was set to %\begin{verbatim} % \setcounter{StandardModuleDepth}{1} %\end{verbatim} % at the beginning of the file. % \subsection{Basic usage summary} % \changes{v1.7a}{92/03/11}{Added basic usage summary to spell it out.} % To sum up, the basic structure of a {\tt .doc} file without any % refinements is like this: % \begin{verse}\small % "% "\meta{waffle}\ldots\\ % \quad\ldots \\ % "% \DescribeMacro{\fred}"\\ % "% "\meta{description of fred's use}\\ % \quad\ldots\\ % "% \StopEventually{"\meta{finale code}"}"\\ % \quad\ldots\\ % "% \begin{macro}{\fred}"\\ % "% "\meta{commentary on macro fred}\\ % \verb*+% \begin{macrocode}+\\ % \meta{code for macro fred}\\ % \verb*+% \end{macrocode}+\\ % "% \end{macro}"\\ % \quad\ldots\\ % "% \Finale \PrintIndex \PrintChanges" % \end{verse} % For examples of the use of most---if not all---of the features % described above consult the {\tt doc.doc} source itself. % \subsection{Acknowledgements} % I would like to thank all folks at Mainz and at the Royal Military % College of Science for their help in this project. Especially Brian % and Rainer who pushed everything with their suggestions, bug fixes, % etc. % A big thank you to David Love who brought the documentation % up-to-date again, after I neglected this file for more than two % years. This was most certainly a tough job as many features added to % {\sf doc.doc} after its publication in {\sl TUGboat\/} have been never % properly described. Beside this splendid work he kindly provided % additional code (like ``docstrip'' module formatting) which I think % every {\sf doc.doc} user will be grateful for. % \StopEventually{ % \begin{thebibliography}{1} % \bibitem{book:Buerger} {\sc G. A. B\"urger}. % \newblock Wunderbare Reisen zu Wasser und zu Lande, Feldz\"uge % und lustige Abenteuer des Freyherrn v.\ M\"unchhausen. % \newblock London, 1786 \& 1788. % \bibitem{art:Knuthliterat} {\sc D. E. Knuth}. % \newblock Literate Programming. % \newblock Computer Journal, Vol.~27, {\it pp}.~97--111, May 1984. % \bibitem{book:KnuthA} {\sc D. E. Knuth}. % \newblock Computers \& Typesetting (The \TeX book). % \newblock Addison-Wesley, Vol. A, 1986. % \bibitem{art:Chen} {\sc L. Lamport}. % \newblock MakeIndex: An Index Processor for \LaTeX. % \newblock 17 February 1987. % \newblock (Taken from the file {\tt makeindex.tex} provided with % the program source code.) % \bibitem{art:doc} {\sc Frank Mittelbach}. % \newblock The {\tt doc}-option. % \newblock {\sl TUGboat}, Vol.~10(2), {\it pp}.~245--273, July % 1989. % \bibitem{art:docstrip} {\sc Frank Mittelbach, Denys Duchier and % Johannes Braams}. % \newblock {\tt docstrip.doc} (to appear). % \newblock The file is part of the DOC package. % \bibitem{book:Raspe} {\sc R. E. Raspe} (*1737, \dag 1797). % \newblock Baron M\"unchhausens narrative of his marvellous % travels and campaigns in Russia. % \newblock Oxford, 1785. % \bibitem{art:verbatim} {\sc Rainer Sch\"opf}. % \newblock A New Implementation of \LaTeX's {\tt verbatim} and % {\tt verbatim*} Environments. % \newblock File {\tt verbatim.doc}, version 1.4i. % \end{thebibliography} % ^^A\PrintIndex % ^^A\PrintChanges % \ifmulticols % \addtocontents{toc}{\protect\end{multicols}} % \fi % } ^^A end \StopEventually % \section{The Description of Macros} % Most of the following code is destined for {\tt doc.sty} after % processing with {\tt docstrip} to include the module {\bf style} % indicated here. (All code in this file not appropriate to {\tt % doc.sty} has to be included explicitly by docstrip so that this {\tt % .doc} file can be used as directly as a style file rather than the % stripped version.) The usual font change for the % conditionally-included lines between the \Module{*style} and % \Module{/style} directives is suppressed since only the lines with % an explicit directive are special in this file. % \begin{macrocode} %<*style> % \end{macrocode} % As always, we begin by identifying the latest version of this file % on the VDU and in the {\sf log} file. But only if the macros are % unknown to the system. % \changes{v1.5i}{89/06/07}{Avoid reading the file twice.} % \begin{macrocode} \@ifundefined{macro@cnt}{}{\endinput} \typeout{Style-Option: `doc' \fileversion \@spaces\space\space <\filedate> (FMi)} \typeout{English Documentation \@spaces\@spaces\space <\docdate> (DLo, FMi, RMCS)} % \end{macrocode} % \DescribeMacro\fileversion % \DescribeMacro\filedate % \DescribeMacro\docdate % As you can see I used macros like \verb+\fileversion+ to denote the % version number and the date. They are defined at the very beginning % of the style file (without a surrounding {\sf macrocode} % environment), so I don't have to search for this place here when I % change the version number. You can see their actual outcome in a % footnote to the title. % The first thing that we do next is to get ourselves a new comment % sign. Because all sensible signs are already occupied, we will % choose one that can only be entered indirectly: % {\DoNotIndex{\^}^^A avoid misinterpretion !!!!! VERIFY % \begin{macrocode} \catcode`\^^A=14 % \end{macrocode} % \SortIndex{\string^\string^A}{\string\verb\verbatimchar % \string^\string^A\verbatimchar % \encapchar main} % \subsection{Macros surrounding the `definition parts'} % \begin{macro}{\macrocode} % Parts of the macro definition will be surrounded by the % environment {\sf macrocode}. Put more precisely, they will be % enclosed by a macro whose argument (the text to be set % `verbatim') is terminated by the string % \verb*+% \end{macrocode}+. Carefully note the number of spaces. % \verb+\macrocode+ is defined completely analogously to % \verb+\verbatim+, but because a few small changes were carried % out, almost all internal macros have got new names. We start by % calling the macro \verb+\macro@code+, the macro which bears the % brunt of most of the work, such as \verb+\catcode+ reassignments, % etc. % \changes{v1.5r}{89/11/04}{Support for code line no. (Undoc)} % \begin{macrocode} \def\macrocode{\macro@code % \end{macrocode} % Then we take care that all spaces have the same width, and that % they are not discarded. % \begin{macrocode} \frenchspacing \@vobeyspaces % \end{macrocode} % Before closing, we need to call \verb+\xmacro@code+. It is this % macro that expects an argument which is terminated by the above % string. This way it is possible to keep the \verb+\catcode+ % changes local. % \changes{v1.5r}{89/11/04}{Support for code line no. (Undoc)} % \changes{v1.5t}{89/11/07}{Common code moved to `macro@code.} % \begin{macrocode} \xmacro@code} % \end{macrocode} % \end{macro} % \begin{macro}{\macro@code} % We will now begin with the macro that does the actual work: % \begin{macrocode} \def\macro@code{% % \end{macrocode} % In theory it should consist of a {\sf trivlist} environment, but % the empty space before and after the environment should not be % too large. % \begin{macrocode} \topsep \MacrocodeTopsep % \end{macrocode} % The next parameter we set is \verb+\@beginparpenalty+, in order % to prevent a page break before such an environment. % \begin{macrocode} \@beginparpenalty \predisplaypenalty % \end{macrocode} % We then start a \verb+\trivlist+, set \verb+\parskip+ back to % zero and start an empty \verb+\item+. % \begin{macrocode} \trivlist \parskip \z@ \item[]% % \end{macrocode} % Additionally, everything should be set in {\tt typewriter} font. % Some people might prefer it somewhat differently; because of this % the font choice is % macro-driven.\footnote{The font change has to be placed % {\em after\/} % the {\tt\bslash item}. Otherwise a change to % {\tt\bslash baselineskip} will affect the % paragraph above.} % \begin{macrocode} \macro@font % \end{macrocode} % Because \verb+\item+ sets various parameters, we have found it % necessary to alter some of these retrospectively. % \begin{macrocode} \leftskip\@totalleftmargin \advance\leftskip\MacroIndent \rightskip\z@ \parindent\z@ \parfillskip\@flushglue % \end{macrocode} % The next line consists of the \LaTeX{} definition of \verb+\par+ % used in \verb+\verbatim+ and should result in blank lines being % shown as blank lines. % \changes{v1.5l}{89/09/10}{Code line numbers supported.} % \changes{v1.5t}{89/11/07}{Call `leavevmode to get `everypar on % blank lines.} % \changes{v1.7c}{92/3/24}{Added `interlinepenalty to `par from % verbatim.sty} % \begin{macrocode} \blank@linefalse \def\par{\ifblank@line \leavevmode\fi \blank@linetrue\@@par \penalty\interlinepenalty} % \end{macrocode} % What use is this definition of \verb+\par+\,? We use the macro % \verb+\obeylines+ of \cite{book:KnuthA} which changes all \verb+^^M+ % to \verb+\par+ so that each can control its own indentation. % Next we must also ensure that all special signs are normalized; % that is, they must be given \verb+\catcode+ $12$. % \begin{macrocode} \obeylines \let\do\@makeother \catcode`\`\active \@noligs \dospecials % \end{macrocode} % \changes{v1.5t}{89/11/07}{Common code added.} % \changes{v1.5w}{90/02/05}{Skip of `@totalleftmargin added.} % If indexing by code lines is switched on the line number is % incremented and set appropriately. We also check whether the start of % the next line indicates a {\tt docstrip} module directive and process % it appropriately if so using "\check@module". % \begin{macrocode} \global\@newlistfalse \global\@minipagefalse \ifcodeline@index \everypar{\global\advance\c@CodelineNo\@ne \llap{\theCodelineNo\ \hskip\@totalleftmargin}% \check@module}% \else \everypar{\check@module}% \fi % \end{macrocode} % We also initialize the cross-referencing feature by calling % \verb+\init@crossref+. This will start the scanning mechanism % when encountering an escape character. % \begin{macrocode} \init@crossref} % \end{macrocode} % \end{macro} % \begin{macro}{\ifblank@line} % \begin{macro}{\blank@linetrue} % \begin{macro}{\blank@linefalse} % \verb+\ifblank@line+ is the switch used in the definition above. % In the original {\sf verbatim} environment the \verb+\if@tempswa+ % switch is used. This is dangerous because its value may change % while processing lines in the {\sf macrocode} environment. % \begin{macrocode} \newif\ifblank@line % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \begin{macro}{\endmacrocode} % Because we have begun a {\sf trivlist} environment in the {\sf % macrocode} environment, we must also end it. We must also act on % the value of the "pm@module" flag (see below) and empty % "\everypar". % \changes{v1.5r}{89/11/04}{Support for code line no. (Undoc)} % \begin{macrocode} \def\endmacrocode{% \ifpm@module \endgroup \pm@modulefalse \fi \everypar{}% \global\@inlabelfalse \endtrivlist % \end{macrocode} % Additionally \verb+\close@crossref+ is used to do anything needed % to end the cross-referencing mechanism. % \begin{macrocode} \close@crossref} % \end{macrocode} % \end{macro} % \begin{macro}{\MacroFont} % Here is the default definition for the \verb+\MacroFont+ macro. % If the new font selection scheme is in use we suppress changes % of math fonts thereby making doc much faster. % \changes{v1.5x}{90/02/17}{`math@fontsfalse added for new font sel.} % \changes{v1.7a}{92/03/13}{Added `reset@font for NFSS.} % \begin{macrocode} \@ifundefined{MacroFont}{% \ifx\undefined\selectfont \def\MacroFont{\small\tt}\else \def\MacroFont{\math@fontsfalse\reset@font\small\tt}\fi }{} % \end{macrocode} % \end{macro} % \begin{macro}{\AltMacroFont} % \begin{macro}{\macro@font} % \changes{v1.7a}{92/03/12}{Added to support distinction of modules.} % \changes{v1.7c}{92/03/26}{Altered font change for OFSS.} % Although most of the macro code is set in "\MacroFont" we want to be % able to switch to indicate module code set in "\AltMacroFont". % "\macro@font" keeps track of which one we're using. We can't do the % same thing sensibly in OFSS as in NFSS. % \begin{macrocode} \@ifundefined{AltMacroFont}{% \ifx\undefined\selectfont \def\AltMacroFont{\small\tt}\else \def\AltMacroFont{\math@fontsfalse\small\reset@font\it\tt}\fi }{} \let\macro@font=\MacroFont % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\check@module} % \begin{macro}{\ifpm@module} % \changes{v1.7a}{92/03/12}{Added.} % This is inserted by "\everypar" at the start of each macrocode line to % check whether it starts with module information. (Such information is % of the form "%<"\meta{switch}">", where the "%" must be at the % start of the line and \meta{switch} comprises names with various % possible separators and a possible leading "+", "-", "*" or "/" % \cite{art:docstrip}. All that concerns us here is what the first % character of \meta{switch} is.) First it checks the "pm@module" % flag in case the previous line had a non-block module % directive i.e., not "%<*" or "%" appropriately and then change to the % special macro font inside a group which will be ended at the start % of the next line. If the apparent module directive is missing the % terminating ">" this will lose, but then so will the {\tt docstrip} % implementation. An alternative strategy would be to have % "\pm@module" make ">" active and clear a flag set here to indicate % processing the directive. Appropriate action could then be taken if % the flag was found still to be set when processing the next line. % \changes{v1.7a}{92/03/12}{Added.} % \changes{v1.7i}{92/07/11}{Support for fonts depending on nesting.} % \begin{macrocode} \def\pm@module#1>{\pm@moduletrue \Module{#1}\begingroup % \end{macrocode} % We switch to a special font as soon the nesting is higher than % the current value of "\c@StandardModuleDepth". We do a local % update to the "\guard@level" here which will be restored after % the current input line. % \begin{macrocode} \advance\guard@level\@ne \ifnum\guard@level>\c@StandardModuleDepth\AltMacroFont\fi % \end{macrocode} % \end{macro} % \begin{macro}{\star@module} % \begin{macro}{\slash@module} % \changes{v1.7a}{92/03/12}{Added.} % \changes{v1.7f}{92/05/16}{Take account of nested guards.} % \changes{v1.7i}{92/07/11}{Add counter to determine when to switch to % special font.} % If the start or end of a module {\em block\/} is indicated, after % setting the guard we have to check whether a change in the macrocode % font should be done. This will be the case if we are already inside % a block or are ending the outermost block. If so, we globally % toggle the font for subsequent macrocode sections between the normal % and special form, switching to the new one immediately. % \changes{v1.7i}{92/07/17}{Support for fonts depending on module % nesting} % \begin{macrocode} \def\star@module#1>{% \Module{#1}% \global \advance \guard@level\@ne \ifnum \guard@level>\c@StandardModuleDepth \global\let\macro@font=\AltMacroFont \macro@font \fi} \def\slash@module#1>{% \Module{#1}% \global \advance \guard@level\m@ne \ifnum \guard@level=\c@StandardModuleDepth \global\let\macro@font\MacroFont \macro@font \fi % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\c@StandardModuleDepth} % \changes{v1.7i}{92/07/11}{Counter added.} % Counter defining up to which level modules are considered part of % the main code. If, for example, the whole code is surrounded by % a |%<*style>| module we better set this counter to |1| to avoid % getting the whole code be displayed in typewriter italic. % \begin{macrocode} \newcounter{StandardModuleDepth} % \end{macrocode} % \end{macro} % \begin{macro}{\guard@level} % \changes{v1.7f}{92/05/16}{Added.} % We need a counter to keep track of the guard nesting. % \begin{macrocode} \newcount \guard@level % \end{macrocode} % \end{macro} % \begin{macro}{\Module} % \changes{v1.7a}{92/03/12}{Added.} % \changes{v1.7d}{92/04/25}{Use sans font for modules.} % This provides a hook to determine the way the module directive is % set. It gets as argument everything between the angle brackets. % The default is to set the contents in sans serif text between % $\langle\,\rangle$ with the special characters suitably "\mathcode"d % by "\mod@math@codes". (You can't just set it in a sans text font % because normally "|" will print as an em-dash.) This is done % differently depending on whether we have the NFSS or the old one. In % the latter case we can easily change "\fam" appropriately. % \begin{macrocode} \@ifundefined{Module}{% \ifx\undefined\selectfont \def\Module#1{{\mod@math@codes$\fam\sffam\langle #1\rangle$}} % \end{macrocode} % With NFSS what we probably {\em should\/} do is change to a new % "\mathversion" but I (Dave Love) haven't spotted an easy way to do so % correctly if the document uses a version other than "normal". (We % need to know in what font to set the other groups.) This uses a new % math alphabet rather than version and consequently has to worry about % whether we're using {\sf oldlfont} or not. I expect there's a better % way\ldots % \begin{macrocode} \else \expandafter\ifx\csname ds@oldlfont\endcsname\relax \def\Module#1{{\mod@math@codes$\langle\sfmath{#1}\rangle$}} \else \def\Module#1{{\mod@math@codes$\langle{\sfmath #1}\rangle$}} \fi \fi}{} % \end{macrocode} % \end{macro} % \begin{macro}{\mod@math@codes} % \changes{v1.7c}{92/03/26}{Added.} % As well as `words', the module directive text might contain any of the % characters "*/+-,&|!()" for the current version of {\sf docstrip}. We % only need special action for two of them in the math code changing % required above: "|" is changed to a "\mathop" (it's normally % \verb+"026A+) and "&" is also made a "\mathop", but in family 0. % Remember that "&" will not have a special catcode when it's % encountered. % \begin{macrocode} \def\mod@math@codes{\mathcode`\|="226A \mathcode`\&="2026} % \end{macrocode} % \end{macro} % \begin{macro}{\sfmath} % \changes{v1.7c}{92/03/26}{Added.} % \changes{v1.7d}{92/04/25}{Use sans font for modules.} % If NFSS is in use we need a new math alphabet which uses a sans serif % font. % \begin{macrocode} \ifx\selectfont\undefined \else \ifx\sfmath\undefined \newmathalphabet*{\sfmath}{\sfdefault}{m}{n}\fi % \end{macrocode} % \end{macro} % \begin{macro}{\MacrocodeTopsep} % \begin{macro}{\MacroIndent} % In the code above, we have used two registers. Therefore we have % to allocate them. The default values might be overwritten with % the help of the \verb+\DocstyleParms+ macro. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)} % \changes{v1.5y}{90/02/24}{Default changed.} % \changes{v1.6b}{90/06/15}{`rm moved before `scriptsize to % avoid unnecessary fontwarning.} % \begin{macrocode} \newskip\MacrocodeTopsep \MacrocodeTopsep = 3pt plus 1.2pt minus 1pt \newdimen\MacroIndent \settowidth\MacroIndent{\rm\scriptsize 00\ } % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\macrocode*} % \begin{macro}{\endmacrocode*} % Just as in the {\sf verbatim} environment, there is also a `star' % variant of the {\sf macrocode} environment in which a space is % shown by the symbol \verb*+ +. Until this moment, I have not yet % used it (it will be used in the description of the definition of % \verb+\xmacro@code+ below) but it's exactly on this one occasion % {\em here\/} that you can't use it % (cf.\ M\"unchhausens Marsh problem)\footnote{Karl Friedrich % Hieronymus Frhr.\ v.\ M\"unchhausen (*1720, \dag1797). % Several books were written about fantastic adventures % supposedly told by him (see \cite{book:Raspe} or % \cite{book:Buerger}). In one story he escaped from the % marsh by pulling himself out by his hair.} % directly. Because of this, on this one occasion we'll cheat % around the problem with an additional comment character. But now % back to \verb+\macrocode*+. We start with the macro % \verb+\macro@code+ which prepares everything and then call the % macro \verb+\sxmacro@code+ whose argument is terminated by the % string \verb*+% \end{macrocode*}+. % \begin{macrocode} \@namedef{macrocode*}{\macro@code\sxmacro@code} % \end{macrocode} % As we know, \verb+\sxmacro@code+ and then \verb+\end{macrocode*}+ % (the macro, not the string), will be executed, so that for a % happy ending we still need to define the macro % \verb+\endmacrocode*+. % \begin{macrocode} \expandafter\let\csname endmacrocode*\endcsname = \endmacrocode % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\xmacro@code} \catcode`\!=\catcode`\% ^^A In this section there must not be ^^A any exclamation marks. ^^A % As already mentioned, the macro \verb+\xmacro@code+ expects an % argument delimited by the string \verb*+% \end{macrocode}+. At % the moment that this macro is called, the \verb+\catcode+ of % \TeX's special characters are 12 (`other') or 13 (`active'). % Because of this we need to utilize a different escape character % during the definition. This happens locally. % \begin{macrocode*} \begingroup \catcode`\|=\z@ \catcode`\[=\@ne \catcode`\]=\tw@ % \end{macrocode*} % Additionally, we need to ensure that the symbols in the above % string contain the \verb+\catcode+$\,$s which are available % within the {\sf macrocode} environment. % \begin{macrocode*} \catcode`\{=12 \catcode`\}=12 \catcode`\%=12 \catcode`\ =\active \catcode`\\=\active !% \end{macrocode*} ! Next follows the actual definition of \verb+\macro@code+; ! notice the ! use of the new escape character. We manage to get the argument ! surrounded by the string \verb+\end{macrocode}+, but at the end ! however, in spite of the actual characters used during the ! definition of ! this macro, \verb+\end+ with the argument \verb+{macrocode}+ ! will be executed, to ensure a balanced environment. ! \begin{macrocode*} |gdef|xmacro@code#1% \end{macrocode}[#1|end[macrocode]] !% \end{macrocode*} ! \begin{macro}{\sxmacro@code} ! The definition of \verb+\sxmacro@code+ is completely analogous, ! only ! here a slightly different terminating string will be used. ! Note that the space is not active in this environment. ! \begin{macrocode} |catcode`| =12 |gdef|sxmacro@code#1% \end{macrocode*}[#1|end[macrocode*]] !% \end{macrocode} ! because the \verb+\catcode+ changes have been made local by ! commencing a ! new group, there now follows the matching \verb+\endgroup+ ! in a rather ! unusual style of writing. ! \begin{macrocode} |endgroup !% \end{macrocode} \catcode`\!=12 % \end{macro} % \end{macro} % \subsection{Macros for the `documentation parts'} % \begin{macro}{\DescribeMacro} % \begin{macro}{\Describe@Macro} % \changes{v1.5v}{90/01/28}{Macro added.} % \changes{v1.5j}{89/06/09}{ignorespaces added as a temporary fix.} % \begin{macro}{\DescribeEnv} % \begin{macro}{\Describe@Env} % \changes{v1.5v}{90/01/28}{Macro added.} % \changes{v1.5j}{89/06/09}{ignorespaces added as a temporary fix.} % The \verb+\DescribeMacro+ and \verb+\DescribeEnv+ macros should % print their arguments in the margin and produce an index entry. % We simply use \verb+\marginpar+ to get the desired result. This % is however not the best solution because the labels might be % slightly misplaced. One also might get a lot of `marginpar moved' % messages which are hard-wired into the \LaTeX{} output % routine.\footnote{It might be better to change these macros into % environments like the {\sf macro} environment.} First we change % to horizontal mode if necessary. The \LaTeX{} macros % \verb+\@bsphack+ and \verb+\@esphack+ are used to make those % commands invisible (i.e.\ to normalize the surrounding space and % to make the \verb+\spacefactor+ transparent). % \changes{v1.5v}{90/01/28}{`MakePrivateLetters added.} % \begin{macrocode} \def\DescribeMacro{\leavevmode\@bsphack % \end{macrocode} % When documenting the code for the {\tt amstex.sty} option we % encountered a bug: the \verb+\catcode+ of \verb+@+ was active and % therefore couldn't be used in command names. So we first have to % make sure that we get all \verb+\catcode+s right by calling % \verb+\MakePrivateLetters+ inside a group. Then we call % \verb+\Describe@Macro+ to do the work. % \begin{macrocode} \begingroup\MakePrivateLetters\Describe@Macro} \def\Describe@Macro#1{\endgroup \marginpar{\raggedleft\PrintDescribeMacro{#1}}% % \end{macrocode} % Note the use of \verb+\raggedleft+ to place the output flushed % right. Finally we call a macro which produces the actual index % entry and finish with \verb+\@esphack+ to leave no % trace.\footnote{The whole mechanism won't work because % of the {\tt\bslash leavevmode} in front. % As a temporary change {\tt\bslash ignorespaces} % is added.} % \begin{macrocode} \SpecialUsageIndex{#1}\@esphack\ignorespaces} % \end{macrocode} % The \verb+\DescribeEnv+ macro is completely analogous. % \changes{v1.5v}{90/01/28}{`MakePrivateLetters added.} % \begin{macrocode} \def\DescribeEnv{\leavevmode\@bsphack\begingroup\MakePrivateLetters \Describe@Env} \def\Describe@Env#1{\endgroup \marginpar{\raggedleft\PrintDescribeEnv{#1}}% \SpecialEnvIndex{#1}\@esphack\ignorespaces} % \end{macrocode} % To put the labels in the left margin we have to use the % \verb+\reversemarginpar+ declaration. (This means that the {\tt % doc.sty} can't be used with all style options.) We also make the % \verb+\marginparpush+ zero and \verb+\marginparwidth+ suitably % wide. % \changes{v1.5d}{89/4/28}{marginparwith setting added.} % \begin{macrocode} \reversemarginpar \setlength\marginparpush{0pt} \setlength\marginparwidth{8pc} % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \begin{macro}{\bslash} % \changes{v1.7a}{92/02/26}{Moved `bslash documentation to `user % interface' part} % We start a new group in which to hide the alteration of % \verb+\catcode+$\,$s, and make \verb+|+ introduce commands, % whilst \verb+\+ becomes an `other' character. % \begin{macrocode} {\catcode`\|=\z@ \catcode`\\=12 % \end{macrocode} % Now we are able to define \verb+\bslash+ (globally) to generate a % backslash of \verb+\catcode+ `other'. We then close this group, % restoring original \verb+\catcode+$\,$s. % \SpecialEscapechar{\|} % \begin{macrocode} |gdef|bslash{\}} % \end{macrocode} % \end{macro} % \begin{macro}{\verbatim} % \begin{macro}{\verbatim*} % \changes{v1.7i}{92/07/12}{Added changed definition for verbatim!*.} % The {\sf verbatim} environment holds no secrets; it consists of % the normal \LaTeX{} environment. We also set the % \verb+\@beginparpenalty+ and change to the font given by % \verb+\MacroFont+. % \begin{macrocode} \def\verbatim{\@beginparpenalty \predisplaypenalty \@verbatim \MacroFont \frenchspacing \@vobeyspaces \@xverbatim} % \end{macrocode} % We deal in a similar way with the star form of this environment. % \begin{macrocode} \@namedef{verbatim*}{\@beginparpenalty \predisplaypenalty \@verbatim \MacroFont \@sxverbatim} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\@verbatim} % Additionally we redefine the \verb+\@verbatim+ macro so that it % suppresses \verb+%+ characters at the beginning of the line. The % first lines are copied literally from {\tt latex.tex}. % \changes{v1.7i}{92/07/12}{Added `@@par to clear possible `parshape.} % \begin{macrocode} \def\@verbatim{\trivlist \item[]\if@minipage\else\vskip\parskip\fi \leftskip\@totalleftmargin\rightskip\z@ \parindent\z@\parfillskip\@flushglue\parskip\z@ \@@par \@tempswafalse % \end{macrocode} % \verb+\@verbatim+ sets \verb+^^M+, the end of line character, to % be equal to \verb+\par+. This control sequence is redefined % here; \verb+\@@par+ is the paragraph primitive of \TeX. % \changes{v1.7c}{92/3/24}{Added `interlinepenalty to `par from % verbatim.sty} % \begin{macrocode} \def\par{\if@tempswa\hbox{}\fi\@tempswatrue\@@par \penalty\interlinepenalty % \end{macrocode} % We add a control sequence \verb+\check@percent+ to the definition % of \verb+\par+ whose task it is to check for a percent character. % \begin{macrocode} \check@percent}% % \end{macrocode} % The rest is again copied literally from {\tt latex.tex} (less % "\tt"). % \changes{v1.7a}{92/02/26}{Removed redundant `tt.} % \begin{macrocode} \obeylines \catcode`\`\active \@noligs \let\do\@makeother \dospecials} % \end{macrocode} % \end{macro} % \begin{macro}{\check@percent} % Finally we define \verb+\check@percent+. Since this must compare % a character with a percent sign we must first (locally) change % percent's \verb+\catcode+ so that it is seen by \TeX. The % definition itself is nearly trivial: grab the following % character, check if it is a \verb+%+, and insert it again if not. % At the end of the {\sf verbatim} environment this macro will peek % at the next input line. In that case the argument to % \verb+\check@percent+ might be a \verb+\par+ or a macro with % arguments. Therefore we make the definition \verb+\long+ % (\verb+\par+ allowed) and use the normal \verb+\next+ mechanism % to reinsert the argument after the \verb+\fi+ if necessary. % \changes{v1.5i}{89/06/07}{Definition changed to `long'} % \changes{v1.5i}{89/06/07}{Macro `next' used to guard against % macro with arguments} % There is a subtle problem here, the equal sign between % \verb+\next+ and \verb+#1+ is actually necessary. Do you see why? % The omission of this token once caused a funny error. % \changes{v1.5u}{89/11/14}{equal sign added.} % \begin{macrocode} {\catcode`\%=12 \long\gdef\check@percent#1{\ifx #1%\let\next\@empty \else \let\next=#1\fi \next}} % \end{macrocode} % \end{macro} % \begin{macro}{\verb} % \changes{v1.7a}{92/02/27}{Now warns about newlines (from % newdoc with `@noligs added).} % We re-define "\verb" to check for newlines in its argument since a % missing delimiter is difficult to detect in {\sf doc} source. % Although the code is somewhat different, the % method follows \cite{art:verbatim}, which should be % consulted for commentary. Perhaps there should be a font-changing % hook rather than just using "\tt", but if so it probably should be % different from "\MacroFont" since that normally includes "\small" % and would look wrong inline. (There's no particular reason for % using lower-casing here to % splice in the relevant character, rather than the upper-casing used in % the definition of "\SpecialEscapechar" % (\S\ref{sect:specialescapechar}); remember that the case % shift doesn't touch the control sequence tokens.) % \changes{v1.7a}{92/02/28}{Added math math check (from verbatim.sty).} % \begin{macrocode} \begingroup \lccode`\~=`\^^M \lowercase{% \gdef\verb{\relax \ifmmode \hbox \else \leavevmode\null \fi \bgroup \tt \catcode`\`\active \@noligs \let~\verb@err \catcode`\^^M\active \let\do\@makeother \dospecials \@ifstar\@sverb{\@vobeyspaces \frenchspacing \@sverb}}} \endgroup \def\verb@err{\egroup\@latexerr{\string\verb\space command ended by end of line.}\@ehc} % \end{macrocode} % \end{macro} % \begin{macro}{\@sverb} % \changes{v1.7a}{92/02/27}{Added for `verb change.} % \changes{v1.7a}{92/02/28}{Now same as in verbatim.sty.} % See \cite{art:verbatim} for commentary. % \begin{macrocode} \def\@sverb#1{% \catcode`#1\active \lccode`\~`#1% \lowercase{\let~\egroup}} % \end{macrocode} % \end{macro} % \begin{macro}{\macro} % \begin{macro}{\m@cro@} % \changes{v1.5v}{90/01/28}{`macro@ renamed to `m@cro@ since AmSTeX % defines another macro of the same name.} % \begin{macro}{\macro@cnt} % \begin{macro}{\macro@level} % \label{page:macro} The {\sf macro} environment is implemented as % a {\sf trivlist} environment, whereby in order that the macro % names can be placed under one another in the margin % (corresponding to the macro's nesting depth), the macro % \verb+\makelabel+ must be altered. In order to store the nesting % depth, we use a counter. We also need a counter to count the % number of nested {\sf macro} environments. % \changes{v1.5k}{89/08/17}{Fix for save stack problem.} % \begin{macrocode} \newcount\macro@cnt \macro@cnt=0 \newcount\macro@level \macro@level=0 % \end{macrocode} % The environment takes an argument---the macro name to be % described. Since this name may contain special `letters' we have % to re-\verb+\catcode+ them before scanning the argument. This is % done by the \verb+\MakePrivateLetters+ macro. On toplevel we % start with \verb+\begingroup+ otherwise we simply re-catcode the % special letters and call \verb+\m@cro@+. Therefore the % \verb+\endgroup+ at the start of this macro will cancel the group % opened by the \verb+\begin+ macro if we are already inside a {\sf % macro} environment. This avoids problems with the save-stack on % small systems since then the \verb+\trivlist+ used later on will % not put anything onto this stack. % \changes{v1.5k}{89/08/17}{Fix for save stack problem.} % \changes{v1.7a}{92/02/26}{Catcode backslash to other (from newdoc).} % \begin{macrocode} \def\macro{% \ifnum\macro@level=\z@ \begingroup \fi \catcode`\\12 \MakePrivateLetters \m@cro@} % \end{macrocode} % After scanning the argument we close the group to get the normal % \verb+\catcode+$\,$s back. Then we assign a special value to % \verb+\topsep+ and start a {\sf trivlist} environment. % Additionally we advance the \verb+\macro@level+ counter to keep % track of the number of nested {\sf macro} environments. % \changes{v1.5f}{89/5/07}{MacroTopsep parameter added.} % \changes{v1.5k}{89/08/17}{Fix for save stack problem.} % \begin{macrocode} \long\def\m@cro@#1{\endgroup \topsep\MacroTopsep \trivlist \advance\macro@level\@ne % \end{macrocode} % We also save the name being described in \verb+\saved@macroname+ for % use in conjunction with the \verb+\changes+ macro. % \begin{macrocode} \edef\saved@macroname{\string#1}% % \end{macrocode} % Now there follows a variation of \verb+\makelabel+ which is used % should the environment not be nested, or should it lie between % two successive \verb+\begin{macro}+ instructions or explanatory % text. One can recognize this with the switch \verb+\if@inlabel+ % which will be \verb+true+ in the case of successive \verb+\item+ % commands. % \begin{macrocode} \def\makelabel##1{\llap{##1}}% % \end{macrocode} % If \verb+@inlabel+ is \verb+true+ and if $\verb=\macro@cnt= > 0$ % then the above definition needs to be changed, because in this % case \LaTeX{} would otherwise put the labels all on the same line % and this would lead to them being overprinted on top of each % other. Because of this \verb+\makelabel+ needs to be redefined % in this case. % \begin{macrocode} \if@inlabel % \end{macrocode} % If \verb+\macro@cnt+ has the value $1$, then we redefine % \verb+\makelabel+ so that the label will be positioned in the % second line of the margin. As a result of this, two macro names % appear correctly, one under the other. It's important whilst % doing this that the generated label box is not allowed to have % more depth than a normal line since otherwise the distance % between the first two text lines of \TeX{} will be incorrectly % calculated. The definition should then look like: %\begin{verbatim} % \def\makelabel##1{\llap{\vtop to \baselineskip % {\hbox{\strut}\hbox{##1}\vss}}} %\end{verbatim} % Completely analogous to this is the case where labels need to be % placed one under the other. The lines above are only an example % typeset with the {\sf verbatim} environment. To produce the real % definition we save the value of \verb+\macro@cnt+ in % \verb+\count@+ and empty the temp macro \verb+\@tempa+ for later % use. % \begin{macrocode} \let\@tempa\@empty \count@\macro@cnt % \end{macrocode} % In the following loop we append for every already typeset label % an \verb+\hbox{\strut}+ to the definition of \verb+\@tempa+. % \begin{macrocode} \loop \ifnum\count@>\z@ \edef\@tempa{\@tempa\hbox{\strut}}\advance\count@\m@ne \repeat % \end{macrocode} % Now be put the definition of \verb+\makelabel+ together. % \changes{v1.5b}{89/04/27}{vbox to vtop changed in makelabel (test)} % \changes{v1.5e}{89/04/28}{ht strutbox changed to baselineskip (test)} % \begin{macrocode} \edef\makelabel##1{\llap{\vtop to\baselineskip {\@tempa\hbox{##1}\vss}}}% % \end{macrocode} % Next we increment the value of the nesting depth counter. This % value inside the {\sf macro} environment is always at least one % after this point, but its toplevel definition is zero. Provided % this environment has been used correctly, $\verb+\macro@cnt+=0$ % should not occur when $\verb+@inlabel+=\sf true$. It is however % possible if this environment is used within other list % environments (but this would have little point). % \begin{macrocode} \advance \macro@cnt \@ne % \end{macrocode} % If \verb+@inlabel+ is false we reset \verb+\macro@cnt+ assuming % that there is enough room to print the macro name without % shifting. % \begin{macrocode} \else \macro@cnt\@ne \fi % \end{macrocode} % Now the label will be produced using \verb+\item+. The following % line is only a hack saving the day until a better solution is % implemented. We have to face two problems: the argument might be % a \verb+\par+ which is forbidden in the argument of other macros % if they are not defined as \verb+\long+, or it is something like % \verb+\iffalse+ or \verb+\else+, i.e.\ something which will be % misinterpreted when \TeX{} is skipping conditional text. In both % cases \verb+\item+ will bomb, so we protect the argument by using % \verb+\string+. % \begin{macrocode} \edef\@tempa{\noexpand\item[\noexpand\PrintMacroName{\string#1}]}% \@tempa % \end{macrocode} % At this point we also produce an index entry. Because it is not % known which index sorting program will be used, we do not use the % command \verb+\index+, but rather a command % \verb+\SpecialMainIndex+ after advancing the counter for indexing % by line number. This may be redefined by the user in % order to generate an index entry which will be understood by the % index program in use (note the definition of % \verb+\SpecialMainIndex+ for our installation). % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)} % \begin{macrocode} {\advance\c@CodelineNo\@ne\SpecialMainIndex{#1}\nobreak}% % \end{macrocode} % The \verb+\nobreak+ is needed to prevent a page break after the % \verb+\write+ produced by the \verb+\SpecialMainIndex+ macro. We % exclude the new macro in the cross-referencing feature, to % prevent spurious non-main entry references. Regarding possibly % problematic arguments, the implementation takes % care of \verb+\par+ and the conditionals are uncritical. % \changes{v1.7a}{92/03/02}{Removed redundant code checking for % `par.}^^A % \begin{macrocode} \DoNotIndex{#1}% % \end{macrocode} % Because the space symbol should be ignored between the % \verb+\begin{macro}{...}+ and the following text we must take % care of this with \verb+\ignorespaces+. % \begin{macrocode} \ignorespaces} % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \begin{macro}{\endmacro} % When ending a {\sf macro} environment we have to cancel the % \verb+\endgroup+ generated by the \verb+\end+ macro as long as we % are still inside another {\sf macro} environment. Therefore % we check the value of the \verb+\macro@level+ counter. Of course % this counter also has to be decremented. % \SpecialIndex{\macro@cnt} % \changes{v1.5k}{89/08/17}{Fix for save stack problem.} % \begin{macrocode} \def\endmacro{% \endtrivlist \ifnum\macro@level>\@ne \advance\macro@level\m@ne \begingroup \fi} % \end{macrocode} % \end{macro} % \begin{macro}{\MacroTopsep} % Here is the default value for the \verb+\MacroTopsep+ parameter % used above. % \begin{macrocode} \newskip\MacroTopsep \MacroTopsep = 7pt plus 2pt minus 2pt % \end{macrocode} % \end{macro} % \subsection{Formatting the margin} % The following three macros should be user definable. % Therefore we define those macros only if they have not already % been defined. % \begin{macro}{\PrintMacroName} % \begin{macro}{\PrintDescribeMacro} % \begin{macro}{\PrintDescribeEnv} % The formatting of the macro name in the left margin is done by % these macros. We first set a \verb+\strut+ to get the height and % depth of the normal lines. Then we change to the % \verb+\MacroFont+ using \verb+\string+ to \verb+\catcode+ the % argument to other (assuming that it is a macro name). Finally we % print a space. The font change remains local since this macro % will be called inside an \verb+\hbox+. % \begin{macrocode} \@ifundefined{PrintMacroName} {\def\PrintMacroName#1{\strut \MacroFont \string #1\ }}{} % \end{macrocode} % We use the same formatting conventions when describing a macro. % \begin{macrocode} \@ifundefined{PrintDescribeMacro} {\def\PrintDescribeMacro#1{\strut \MacroFont \string #1\ }}{} % \end{macrocode} % To format the name of a new environment there is no need to use % \verb+\string+. % \begin{macrocode} \@ifundefined{PrintDescribeEnv} {\def\PrintDescribeEnv#1{\strut \MacroFont #1\ }}{} % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \subsection{Creating index entries by scanning `macrocode'} % The following macros ensure that index entries are created for each % occurrence of a \TeX-like command (something starting with % `\verb+\+') providing indexing has been turned on with "\PageIndex" % or "\CodelineIndex". With the default definitions of % \verb+\SpecialMainIndex+, etc., the index file generated is % intended to be processed by Chen's {\sf makeindex} program % \cite{art:Chen}. % Of course, in {\em this\/} style file itself we've sometimes had to % make \verb+|+ take the r\^ole of \TeX's escape character to % introduce command names at places where \verb+\+ has to belong to % some other category. Therefore, we may also need to recognize % \verb+|+ as the introducer for a command when setting the text % inside the {\sf macrocode} environment. Other users may have the % need to make similar reassignments for their macros. % \begin{macro}{\SpecialEscapechar}\label{sect:specialescapechar} % \begin{macro}{\active@escape@char} % \begin{macro}{\special@escape@char} % The macro \verb+\SpecialEscapechar+ is used to denote a special % escape character for the next {\sf macrocode} environment. It has % one argument---the new escape character given as a % `single-letter' control sequence. Its main purpose is defining % \verb+\special@escape@char+ to produce the chosen escape % character \verb+\catcode+$\,$d to 12 and % \verb+\active@escape@char+ to produce the same character but with % \verb+\catcode+ 13. % The macro \verb+\special@escape@char+ is used to {\em print\/} % the escape character while \verb+\active@escape@char+ is needed % in the definition of \verb+\init@crossref+ to start the scanning % mechanism. % In the definition of \verb+\SpecialEscapechar+ we need an % arbitrary character with \verb+\catcode+ 13. We use `\~{}' and % ensure that it is active. The \verb+\begingroup+ is used to make % a possible change local to the expansion of % \verb+\SpecialEscapechar+. % \changes{v1.7g}{92/6/19}{Making tilde active moved outside % definition} % \begin{macrocode} \begingroup \catcode`\~\active \gdef\SpecialEscapechar#1{% \begingroup % \end{macrocode} % Now we are ready for the definition of % \verb+\active@escape@char+. It's a little tricky: we first % define locally the uppercase code of `\~{}' to be the new escape % character. % \begin{macrocode} \uccode`\~`#1% % \end{macrocode} % Around the definition of \verb+\active@escape@char+ we place an % \verb+\uppercase+ command. Recall that the expansion of % \verb+\uppercase+ changes characters according to their % \verb+\uccode+, but leaves their \verb+\catcode+$\,$s untouched % (cf.\ \TeX{}book page 41). % \begin{macrocode} \uppercase{\gdef\active@escape@char{~}}% % \end{macrocode} % The definition of \verb+\special@escape@char+ is easier, we use % \verb+\string+ to \verb+\catcode+ the argument of % \verb+\SpecialEscapechar+ to 12 and suppress the preceding % \verb+\escapechar+. % \begin{macrocode} \escapechar\m@ne \xdef\special@escape@char{\string#1}% % \end{macrocode} % Now we close the group and end the definition: the value of % \verb+\escapechar+ as well as the \verb+\uccode+ and % \verb+\catcode+ of `\~{}' will be restored. % \begin{macrocode} \endgroup} \endgroup % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \begin{macro}{\init@crossref} % The replacement text of \verb+\init@crossref+ should fulfill the % following tasks: % \begin{itemize} % \parindent4em % \item[1)] % \verb+\catcode+ all characters used in macro names to % 11 (i.e.\ `letter'). % \item[2)] % \verb+\catcode+ the `\verb+\+' character to 13 % (i.e.\ `active'). % \item[3a)] % \verb+\let+ the `\verb+\+' equal \verb+\scan@macro+ % (i.e.\ start the macro scanning mechanism) if there is % no special escape character (i.e.\ the % \verb+\special@escape@char+ is `\verb+\+'). % \item[3b)] % Otherwise \verb+\let+ it equal \verb+\bslash+, i.e.\ % produce a printable \verb+\+. % \item[4)] % Make the \meta{special escape character} active. % \item[5)] % \verb+\let+ the active version of the special escape % character % (i.e.\ the expansion of \verb+\active@escape@char+) equal % \verb+\scan@macro+. % \end{itemize} % The reader might ask why we bother to \verb+\catcode+ the % `\verb+\+' first to 12 (at the end of \verb+\macro@code+) then % re-\verb+\catcode+ it to 13 in order to produce a $\verb+\+_{12}$ % in case 3b) above. This is done because we have to ensure that % `\verb+\+' has \verb+\catcode+ 13 within the {\sf macrocode} % environment. Otherwise the delimiter for the argument of % \verb+\xmacro@code+ would not be found (parameter matching % depends on \verb+\catcode+$\,$s). % Therefore we first re-\verb+\catcode+ some characters. % \begin{macrocode} \begingroup \catcode`\|=\z@ \catcode`\\=\active % \end{macrocode} % We carry out tasks 2) and 3b) first. % \SpecialEscapechar{\|} % \begin{macrocode} |gdef|init@crossref{|catcode`|\|active |let\|bslash % \end{macrocode} % Because of the popularity of the `\verb+@+' character as a % `letter' in macros, we normally have to change its % \verb+\catcode+ here, and thus fulfill task 1). But the macro % designer might use other characters as private letters as well, % so we use a macro to do the \verb+\catcode+ switching. % \SpecialEscapechar\| % \begin{macrocode} |MakePrivateLetters % \end{macrocode} % Now we \verb+\catcode+ the special escape character to 13 and % \verb+\let+ it equal \verb+\scan@macro+, i.e.\ fulfill tasks 4) % and 5). Note the use of \verb+\expandafter+ to insert the chosen % escape character saved in \verb+\special@escape@char+ and % \verb+\active@escape@char+. % \SpecialEscapechar\| % \begin{macrocode} |catcode|expandafter`|special@escape@char|active |expandafter|let|active@escape@char|scan@macro} |endgroup % \end{macrocode} % If there is no special escape character, i.e.\ if % \verb+\SpecialEscapechar+ is \verb+\\+, the second last line will % overwrite the previous definition of $\verb+\+_{13}$. In this % way all tasks are fulfilled. % For happy documenting we give default values to % \verb+\special@escape@char+ and \verb+\active@escape@char+ with % the following line: % \begin{macrocode} \SpecialEscapechar{\\} % \end{macrocode} % \end{macro} % \begin{macro}{\MakePrivateLetters} % Here is the default definition of this command, which makes just % the \verb+@+ into a letter. The user may change it if he/she % needs more or other characters masquerading as letters. % \begin{macrocode} \@ifundefined{MakePrivateLetters} {\let\MakePrivateLetters\makeatletter}{} % \end{macrocode} % \end{macro} % \begin{macro}{\close@crossref} % At the end of a cross-referencing part we prepare ourselves for % the next one by setting the escape character to `\verb+\+'. % \begin{macrocode} \def\close@crossref{\SpecialEscapechar\\} % \end{macrocode} % \end{macro} % \subsection{Macros for scanning macro names} % \begin{macro}{\scan@macro} % \changes{v1.5k}{89/09/04}{Support for checksum added.} % \begin{macro}{\macro@namepart} % The \verb+\init@crossref+ will have made \verb+\active+ our % \verb+\special@escape@char+, so that each % \verb+\active@escape@char+ will invoke \verb+\scan@macro+ when % within the {\sf macrocode} environment. By this means, we can % automatically add index entries for every \TeX-like command which % is met whilst setting (in verbatim) the contents of {\sf % macrocode} environments. % \begin{macrocode} \def\scan@macro{% % \end{macrocode} % First we output the character which triggered this macro. Its % version \verb+\catcode+$\,$d to 12 is saved in % \verb+\special@escape@char+. We also call \verb+\step@checksum+ % to generate later on a proper check-sum (see section % \ref{sec:checksum} for details). % \begin{macrocode} \special@escape@char \step@checksum % \end{macrocode} % If the {\sf macrocode} environment contains, for example, the % command \verb+\\+, the second \verb+\+ should not start the % scanning mechanism. Therefore we use a switch to decide if % scanning of macro names is allowed. % \begin{macrocode} \ifscan@allowed % \end{macrocode} % The macro assembles the letters forming a \TeX\ command in % \verb+\macro@namepart+ so this is initially cleared; we then set % \verb+\next+ to the {\it first\/} character following the % \verb+\+ and call \verb+\macro@switch+ to determine whether that % character is a letter or not. % \begin{macrocode} \let\macro@namepart\@empty \def\next{\futurelet\next\macro@switch}% % \end{macrocode} % As you recognize, we actually did something else, because we have % to defer the \verb+\futurelet+ call until after the final % \verb+\fi+. If, on the other hand, the scanning is disabled we % simply \verb+\let+ \verb+\next+ equal `empty'. % \begin{macrocode} \else \let\next\@empty \fi % \end{macrocode} % Now we invoke \verb+\next+ to carry out what's needed. % \begin{macrocode} \next} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\ifscan@allowed} % \begin{macro}{\scan@allowedtrue} % \begin{macro}{\scan@allowedfalse} % \verb+\ifscan@allowed+ is the switch used above to determine if % the \verb+\active@escape@char+\SpecialIndex{\active@escape@char} % should start the macro scanning mechanism. % \begin{macrocode} \newif\ifscan@allowed \scan@allowedtrue % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \begin{macro}{\EnableCrossrefs} % \begin{macro}{\DisableCrossrefs} % At this point we might define two macros which allow the user to % disable or enable the cross-referencing mechanism. Processing of % files will be faster if only main index entries are generated % (i.e., if \verb+\DisableCrossrefs+ is in force). % \begin{macrocode} \def\DisableCrossrefs{\@bsphack\scan@allowedfalse\@esphack} % \end{macrocode} % The macro \verb+\EnableCrossrefs+ will also disable any % \verb+\DisableCrossrefs+ command encountered afterwards. % \begin{macrocode} \def\EnableCrossrefs{\@bsphack\scan@allowedtrue \def\DisableCrossrefs{\@bsphack\@esphack}\@esphack} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\macro@switch} % Now that we have the character which follows the escape character % (in \verb+\next+), we can determine whether it's a `letter' % (which probably includes \verb+@+). % If it is, we let \verb+\next+ invoke a macro which assembles the % full command name. % \begin{macrocode} \def\macro@switch{\ifcat\noexpand\next a% \let\next\macro@name % \end{macrocode} % Otherwise, we have a `single-character' command name. For all % those single-character names, we use \verb+\short@macro+ to % process them into suitable index entries. % \begin{macrocode} \else \let\next\short@macro \fi % \end{macrocode} % Now that we know what macro to use to process the macro name, we % invoke it~\ldots % \begin{macrocode} \next} % \end{macrocode} % \end{macro} % \begin{macro}{\short@macro} % \changes{v1.5c}{89/4/27}{Corrected bad bug by putting the % scan@allowedfalse macro before printing % the argument.} % \changes{v1.7a}{92/03/10}{Ensure character stored in `macro@namepart % as `letter' so index exclusion works.} % This macro will be invoked (with a single character as parameter) % when a single-character macro name has been spotted whilst % scanning within the {\sf macrocode} environment. % First we take a look at the \verb+\index@excludelist+ to see % whether this macro name should produce an index entry. This is % done by the \verb+\ifnot@excluded+ macro which assumes that the % macro name is saved in \verb+\macro@namepart+. The character % mustn't be stored with a special category code or exclusion from % the index won't work, so we employ the case-changing trick used % elsewhere. Since the argument might be an active character, % \verb+\string+ is used to normalize it. % \begin{macrocode} \def\short@macro#1{\begingroup \catcode`\&=11 \uccode`\&=\expandafter`\string#1% \uppercase{\def\macro@namepart{&}}% \endgroup \ifnot@excluded % \end{macrocode} % If necessary the index entry is produced by the macro % \verb+\produce@index+. Depending on the actual character seen, % this macro has to do different things, so we pass the character % as an argument. % \begin{macrocode} \produce@index{#1}\fi % \end{macrocode} % Then we disable the cross-referencing mechanism with % \verb+\scan@allowedfalse+ and print the actual character. The % index entry was generated first to ensure that no page break % intervenes (recall that a \verb+^^M+ will start a new line). % \begin{macrocode} \scan@allowedfalse#1% % \end{macrocode} % After typesetting the character we can safely enable the % cross-referencing feature again. Note that this macro won't be % called (since \verb+\macro@switch+ won't be called) if % cross-referencing is globally disabled. % \begin{macrocode} \scan@allowedtrue } % \end{macrocode} % \end{macro} % \begin{macro}{\produce@index} % \changes{v1.4s}{89/04/23}{Added noexpand to all {\tt\protect\bslash % if} tests % to avoid garbage produced by new active chars} % \changes{v1.4s}{89/04/23}{Used {\tt\protect\bslash string} for the % same reason.} % \changes{v1.5c}{89/4/27}{Corrected bad bug by placing the % scan@allowedfalse macro into short@macro} % This macro is supposed to generate a suitable \verb+\SortIndex+ % command for a given single-letter control sequence. We test % first for the cases which involve active characters (i.e.\ the % backslash, the special escape character (if any), the space and % the \verb+^^M+). Using the \verb+\if+ test (testing for % character codes), we have to ensure that the argument isn't % expanded. % \begin{macrocode} \def\produce@index#1{% \if\noexpand#1\special@escape@char % \end{macrocode} % If the character is the special escape character (or the % `\verb+\+' in case there was none) the \verb+\it@is@a+ macro is % used to produce the actual \verb+\SortIndex+ call. % \begin{macrocode} \scan@allowedfalse \it@is@a\special@escape@char \else % \end{macrocode} % Next comes the test for a `\verb+\+' which must be the % $\verb+\+_{13}$ expanding to \verb+\bslash+. % \begin{macrocode} \if\noexpand#1\bslash \it@is@a\bslash \else % \end{macrocode} % Another possibility is \verb*+ +$_{13}$. Recall that \verb+\space+ % produces a \verb*+ +$_{10}$. % \begin{macrocode} \if\noexpand#1\space \it@is@a\space \else % \end{macrocode} % The last\footnote{Well, it isn't the last active character after % all. I added {\tt \bslash @noligs} some days ago % and now {\tt `} too is active. So we have to make % sure that such characters don't get expanded in % the index.} % possibility of an active character is \verb+^^M+\@. In this case % we don't test for character codes, since it is easier to look if % the character is equal to \verb+\par+. (We are inside the {\sf % macrocode} environment.) % \begin{macrocode} \ifx#1\par % \end{macrocode} % If we end up here we have just scanned a \verb+\^^M+ or something % similar. Since this will be treated like \verb*+\ + by \TeX{} we % produce a corresponding index entry. % \begin{macrocode} \it@is@a\space \else % \end{macrocode} % If it is the token \verb+\relax+ we do nothing. This can't happen % when the `doc' option is used in the way described here, but was % added to allow extensions like the {\tt idxverb} option. % \changes{v1.5t}{89/11/14}{Added `relax as a possible token to allow % extensions.} % \begin{macrocode} \ifx#1\relax \else % \end{macrocode} % The next three branches are needed because of bugs in % our {\sf makeindex} program. You can't produce unbalanced index % entries\footnote{This is possible for \TeX{} if you use % {\tt\string{$_{12}$ \rm or \tt\string}$_{12}$}, % but {\sf makeindex} will complain.} % and you have to double a percent character. To get around these % restrictions we use special macros to produce the \verb+\index+ % calls.\footnote{Brian {\sc Hamilton Kelly} has written fixes for % all three % bugs. When they've found their way through all % installations, % the lines above will be removed. See % page~\pageref{bug:fixes} if you already have them. % (I'm not sure which versions incorporate these, but % 2.11 is OK. See also % \pageref{makeindex:version}.)} % \begin{macrocode} \if\noexpand#1\bgroup \LeftBraceIndex \else \if\noexpand#1\egroup \RightBraceIndex \else \if\noexpand#1\percentchar \PercentIndex \else % \end{macrocode} % All remaining characters are used directly to produce their index % entries. This is possible even for the characters which have % special meanings in the index program, provided we quote the % characters. (This is correctly done in \verb+\it@is@a+.) % \begin{macrocode} \it@is@a{\string#1}% % \end{macrocode} % We now need a whole pile of \verb+\fi+$\,$s to match up with % the \verb+\if+$\,$s. % \begin{macrocode} \fi \fi \fi \fi \fi \fi \fi \fi} % \end{macrocode} % \end{macro} % \begin{macro}{\macro@name} % We now come to the macro which assembles command names which % consist of one or more `letters' (which might well include % \verb+@+ symbols, or anything else which has a \verb+\catcode+ of % 11). % To do this we add the `letter' to the existing definition of % \verb+\macro@namepart+ (which you will recall was originally set % to \verb+\@empty+). % \begin{macrocode} \def\macro@name#1{\edef\macro@namepart{\macro@namepart#1}% % \end{macrocode} % Then we grab hold of the {\em next\/} single character and let % \verb+\more@macroname+ determine whether it belongs to the letter % string forming the command name or is a `non-letter'. % \begin{macrocode} \futurelet\next\more@macroname} % \end{macrocode} % \end{macro} % \begin{macro}{\more@macroname} % This causes another call of \verb+\macro@name+ to add in the next % character, if it is indeed a `letter'. % \begin{macrocode} \def\more@macroname{\ifcat\noexpand\next a% \let\next\macro@name % \end{macrocode} % Otherwise, it finishes off the index entry by invoking % \verb+\macro@finish+. % \begin{macrocode} \else \let\next\macro@finish \fi % \end{macrocode} % Here's where we invoke whatever macro was \verb+\let+ equal to % \verb+\next+. % \begin{macrocode} \next} % \end{macrocode} % \end{macro} % \begin{macro}{\macro@finish} % When we've assembled the full `letter'-string which forms the % command name, we set the characters forming the entire command % name, and generate an appropriate \verb+\index+ command (provided % the command name is not on the list of exclusions). The % `\verb+\+' is already typeset; therefore we only have to output % all `letters' saved in \verb+\macro@namepart+. % \begin{macrocode} \def\macro@finish{% \macro@namepart % \end{macrocode} % Then we call \verb+\ifnot@excluded+ to decide whether we have to % produce an index entry. The construction with \verb+\@tempa+ is % needed because we want the expansion of \verb+\macro@namepart+ in % the \verb+\index+ command.\footnote{The {\tt \bslash index} % command will expand its argument in the {\tt\bslash output} % routine. At this time {\tt\bslash macro@namepart} might have a % new value.} % \begin{macrocode} \ifnot@excluded \edef\@tempa{\noexpand\SpecialIndex{\bslash\macro@namepart}}% \@tempa \fi} % \end{macrocode} % \end{macro} % \subsection[The index exclude list]{The index exclude % list\footnotemark} % \footnotetext{Warning: the incomplete commentary on {\tt % \bslash DoNotIndex} and the macros it calls % was written by Dave Love.} % The internal form of the index exclude list is % \begin{quote} % \meta{macro name}\verb+,+\meta{macro name}\verb+,+ % \ldots\verb+,+ % \end{quote} % where \meta{macro name} is a macro name like % $"\"_{12}"p"{_{11}}"@"_{11}$ or $"\"_{12}"$"_{11}$. Note that the "\" % has category `other' and the other characters in the name are all % `letter', regardless of their normal category. % \begin{macro}{\DoNotIndex} % This macro is used to suppress macro names in the index. It % starts off with a new group because we have to change the % \verb+\catcode+$\,$s of all characters which belong to `letters' % while macros are defined. % \begin{macrocode} \def\DoNotIndex{\begingroup \MakePrivateLetters \catcode`\\12 % \end{macrocode} % Then we call the macro which actually reads the argument given by % the user. % \begin{macrocode} \do@not@index} % \end{macrocode} % \end{macro} % \begin{macro}{\do@not@index} % We make the \verb+\do@not@index+ macro \verb+\long+ % since the user might want to exclude the \verb+\par+ % macro. % \begin{macrocode} \long\def\do@not@index#1{% % \end{macrocode} % It just adds to a token list after finishing the group in which % the catcodes were changed. % \changes{v1.7a}{92/02/26}{Replaced with newdoc version.} % \begin{macrocode} \endgroup \addto@hook\index@excludelist{#1,}} % \end{macrocode} % \end{macro} % \begin{macro}{\addto@hook} % The code for adding tokens (the second argument) to a token list % (the first argument) is taken from~\cite{art:verbatim}, but it needs % to be "\long" in case "\par" is amongst the tokens. % \begin{macrocode} \long\def\addto@hook#1#2{#1\expandafter{\the#1#2}} % \end{macrocode} % \end{macro} % \begin{macro}{\index@excludelist} % We need an initially-empty register for the excluded list. % \begin{macrocode} \newtoks\index@excludelist \index@excludelist{} % \end{macrocode} % \end{macro} % \begin{macro}{\ifnot@excluded} % \changes{v1.7a}{92/02/26}{Replaced with newdoc version.} % \begin{macro}{\expanded@notin} % Now we take a look at the \verb+\index@excludelist+ to see % whether a macro name saved in \verb+\macro@namepart+ should % produce an index entry. This macro is a pseudo \verb+\if+; it % should expand to \verb+\iftrue+ or \verb+\iffalse+ depending on % the contents of \verb+\index@excludelist+. % \begin{macrocode} \begingroup % \end{macrocode} % First we change "\catcode"s so that "\" is `other' and "|" a % temporary for the escape character. This is necessary since our % macro names are stored that way in the "\index@excludelist". % \begin{macrocode} \catcode`\|=0% \catcode`\\=12 % \end{macrocode} % Then we define "\ifnot@excluded" to call "\expanded@notin" with % two arguments: the first is the string "\" followed by the % contents of "\macro@namepart" followed by a "," and the second is % "\the" followed by "\index@excludelist". To achieve the expansion % of "\macro@namepart", i.e.\ to pass its contents, we need a % suitable number of "\expandafter"s. % \SpecialEscapechar{\|} % \begin{macrocode} |gdef|ifnot@excluded{|expandafter |expanded@notin|expandafter{|expandafter \|macro@namepart,}{|the|index@excludelist}} |endgroup % \end{macrocode} % The macro "\expanded@notin" now does the dirty work. It first % defines a macro "\in@@" with a very special parameter text. If % you look closely "\in@@" has three arguments, the first one is % delimited by the first argument of "\expanded@notin" (i.e.\ by % the string starting with a "\" and ending with a "," above), the % second is undelimited (which means that it will get the next % token after our string, and the third is delimited again and will % get the rest up to the token "\in@@". In other words the token % "\in@@" is also used as a delimiter. % \begin{macrocode} \def\expanded@notin#1#2{% \def\in@@##1#1##2##3\in@@{% % \end{macrocode} % Now the replacement text simply compares the second argument % (i.e.\ the undelimited one after our string) to the token % "\expanded@notin". This is an unclosed "\ifx" statement which % means that this macro behaves similar to a normal \TeX{} % conditional. % \begin{macrocode} \ifx\expanded@notin##2}% % \end{macrocode} % After all these preparations we call "\in@@". First we expand the % token after "\in@@" (which is "\the" from the second argument to % "\expanded@notin"). As a result we get the contents of the % "\index@excludelist" inserted after "\in@@". After this contents % we add once more the string we are looking for, then the token % "\expanded@notin" and finally the token "\in@@". % \begin{macrocode} \expandafter\in@@#2#1\expanded@notin\in@@} % \end{macrocode} % Now what happens when the macro "\in@@" above gets called? The % first argument to "\in@@" is delimited by our string. In other % words it will get everything from the contents of % "\index@excludelist" before this string. If the string is not in % "\index@excludelist" then it gets the whole contents, since after % it we had inserted the string one more. In this case the next % token is "\expanded@notin" which gets assigned to the second % argument and the third argument will be empty. If, on the other % hand, the string was inside "\index@excludelist" then the second % argument will not be the token "\expanded@notin" and the third % argument will be all the garbage up to "\in@@". Therefore testing % the seconded argument, as done in the definition of "\in@@" will % tell us whether or not the string is in "\index@includelist" and % this was exactly what we wanted. (Deep breath.) You got % that?\footnote{\TeX{}book page 125. The code described above is % originally due to Michael Spivak who used a similar method within % the \AmSTeX{} macros.} % \end{macro} % \end{macro} % \subsection{Macros for generating index entries} % Here we provide default definitions for the macros invoked to create % index entries; these are either invoked explicitly, or automatically % by \verb+\scan@macro+. As already mentioned, the definitions given % here presuppose that the \verb+.idx+ file will be processed by % Chen's {\sf makeindex} program --- they may be redefined for use % with the user's favourite such program. % To assist the reader in locating items in the index, all such % entries are sorted alphabetically {\em ignoring\/} the initial % `\verb+\+'; this is achieved by issuing an \verb+\index+ command % which contains the `actual' operator for {\sf makeindex}. The % default value for the latter operator is `\verb+@+', but the latter % character is so popular in \LaTeX\ style files that it is necessary % to substitute another character. This is indicated to {\sf % makeindex} by means of an `index style file'; the character selected % for this function is \verb+=+, and therefore this character too must % be specially treated when it is met in a \TeX\ command. A suitable % index style file is provided amongst the supporting files for this % style file in {\tt gind.ist} and is generated from this source by % processing with {\tt docstrip} to extract the module {\bf gind}. A % similar style file {\tt gglo.ist} is supplied for sorting the change % information in the glossary file and is extracted as module {\bf % gglo}. First of all we add some information to the front of the % {\tt .ist} files. \changes{v1.7a}{92/03/11}{Gglo.ist and gind.ist % now derivable from doc.doc with docstrip.} % \begin{macrocode} % %<+gind|gglo>%% This is a MAKEINDEX style file which should be used to %<+gind>%% generate the formatted index for use with the doc %<+gglo>%% generate the formatted change history for use with the doc %<+gind|gglo>%% style option. The TeX commands used below are defined in %<+gind|gglo>%% doc.sty. The commands for MAKEINDEX like `level' %<+gind|gglo>%% `item_x1' are described in `` Makeindex, A General %<+gind|gglo>%% Purpose, Formatter-Independent Index Processor'' by %<+gind|gglo>%% Pehong Chen. %<+gind|gglo> % \end{macrocode} % \begin{macro}{\actualchar} % \begin{macro}{\quotechar} % \begin{macro}{\levelchar} % First come the definitions of \verb+\actualchar+, % \verb+\quotechar+ and \verb+\levelchar+. Note, that our defaults % are not the ones used by the {\sf makeindex} program without a % style file. % \begin{macrocode} %<*style> \@ifundefined{actualchar}{\def\actualchar{=}}{} \@ifundefined{quotechar}{\def\quotechar{!}}{} \@ifundefined{levelchar}{\def\levelchar{>}}{} % %<+gind|gglo>actual '=' %<+gind|gglo>quote '!' %<+gind|gglo>level '>' %<*style> % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \begin{macro}{\encapchar} % The {\sf makeindex} default for the \verb+\encapchar+ isn't % changed. % \begin{macrocode} \@ifundefined{encapchar}{\def\encapchar{|}}{} % \end{macrocode} % \end{macro} % \begin{macro}{\verbatimchar} % We also need a special character to be used as a delimiter for % the \verb+\verb*+ command used in the definitions below. % \begin{macrocode} \@ifundefined{verbatimchar}{\def\verbatimchar{+}}{} % \end{macrocode} % \end{macro} % \begin{macro}{\SpecialIndex} % The \verb+\SpecialIndex+ command creates index entries for % macros. If the argument is \verb+\+$xyz$, the command produces % \verb|\indexentry{|$xyz$\verb|=\verb!*+\|$xyz$\verb|+}{|$n$\verb|}| % given the above defined defaults for \verb+\actualchar+, % \verb+\quotechar+ and \verb+\verbatimchar+. We first remove the % initial `\verb+\+' to get a better index. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)} % \begin{macrocode} \def\SpecialIndex#1{\@bsphack\special@index{\expandafter\@gobble \string#1\actualchar % \end{macrocode} % Then follows the actual entry. A \verb+\quotechar+ is placed % before the \verb+*+ to allow its use as a special {\sf makeindex} % character. Again \verb+\@bsphack+ and \verb+\@esphack+ are used % to make the macros invisible. % \begin{macrocode} \string\verb\quotechar*\verbatimchar\string#1\verbatimchar}% \@esphack} % \end{macrocode} % \end{macro} % \begin{macro}{\SpecialMainIndex} % \begin{macro}{\SpecialUsageIndex} % The \verb+\SpecialMainIndex+ macro is used to cross-reference the % names introduced by the {\sf macro} environment. The action is % as for \verb+\SpecialIndex+, except that {\sf makeindex} is % instructed to `encap'sulate the entry with the string % \verb+|main+ to cause it to generate a call of the \verb+\main+ % macro. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)} % \begin{macrocode} \def\SpecialMainIndex#1{\@bsphack\special@index{\expandafter\@gobble \string#1\actualchar \string\verb \quotechar*\verbatimchar \string#1\verbatimchar \encapchar main}% \@esphack} % \end{macrocode} % The \verb+\SpecialUsageIndex+ is literally the same---only we use % {\tt usage} instead of {\tt main}. % \begin{macrocode} \def\SpecialUsageIndex#1{\@bsphack\index{\expandafter\@gobble\string#1% \actualchar\string\verb\quotechar*\verbatimchar \string#1\verbatimchar \encapchar usage}\@esphack} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\SpecialEnvIndex} % Indexing environments is done a little bit differently; we produce % two index entries with the \verb+\SpecialEnvIndex+ macro: % \begin{macrocode} \def\SpecialEnvIndex#1{\@bsphack % \end{macrocode} % First we sort the environment under its own name stating in the % actual entry that this is an environment. % \begin{macrocode} \index{#1\actualchar{\tt #1} (environment)\encapchar usage}% % \end{macrocode} % The second entry is sorted as a subitem under the key % `environments:'. % \begin{macrocode} \index{environments:\levelchar{\tt #1}\encapchar usage}\@esphack} % \end{macrocode} % Because both entries correspond to `descriptions' of the % environment, we encapsulate the page numbers with the % \verb+\usage+ macro. % \end{macro} % \begin{macro}{\SortIndex} % This macro is used to generate the index entries for any % single-character command that \verb+\scan@macro+ encounters. The % first parameter specifies the lexical order for the character, % whilst the second gives the actual characters to be printed in % the entry. It can also be used directly to generate index entries % which differ in sort key and actual entry. % \begin{macrocode} \def\SortIndex#1#2{\index{#1\actualchar#2}} % \end{macrocode} % \end{macro} % \begin{macro}{\it@is@a} % This macro is supposed to produce a correct \verb+\SortIndex+ % entry for a given character. Since this character might be % recognised as a `command' character by the index program used, % all characters are quoted with the \verb+\quotechar+. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)} % \begin{macrocode} \def\it@is@a#1{\special@index{\quotechar #1\actualchar \string\verb\quotechar*\verbatimchar \quotechar\bslash\quotechar#1\verbatimchar}} % \end{macrocode} % \end{macro} % \begin{macro}{\LeftBraceIndex} % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)} % \begin{macro}{\RightBraceIndex} % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)} % These two macros fix the problems with {\sf makeindex}. Note the % `hack' with \verb+\iffalse}\fi+ to satisfy both \TeX{} and the % {\sf makeindex} program. When this is written to the {\tt .idx} % file \TeX{} will see both braces (so we get a balanced text). % {\sf makeindex} will also see balanced braces but when the actual % index entry is again processed by \TeX{} the brace in between % \verb+\iffalse+ \verb+\fi+ will vanish. % \begin{macrocode} \@ifundefined{LeftBraceIndex}{\def\LeftBraceIndex{% \special@index{\bgroup\actualchar\string\verb\quotechar*\verbatimchar \quotechar\bslash{\verbatimchar\string\iffalse}\string\fi}}}{} \@ifundefined{RightBraceIndex}{\def\RightBraceIndex{% \special@index{\egroup\actualchar\string\iffalse{\string\fi\string\verb \quotechar*\verbatimchar\quotechar\bslash}\verbatimchar}}}{} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\PercentIndex} % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)} % \changes{v1.7c}{92/03/25}{Default now for bug-fixed makeindex} % By default we assume a version of {\sf makeindex} without the % percent bug is being used. % \begin{macrocode} \@ifundefined{PercentIndex} {\def\PercentIndex{\it@is@a\percentchar}}{} % \end{macrocode} % \end{macro} % \begin{macro}{\OldMakeindex} % \changes{v1.7c}{92/03/26}{Replaced `NewMakeIndex.} % \begin{macro}{\percentchar} % Here is one solution for the percent bug in {\sf makeindex}. The % macro \verb+\percentchar+ denotes a \verb+%+$_{12}$. % Calling this from a style option or the driver file sets things % up appropriately.\label{bug:fixes} % \begin{macrocode} \def\OldMakeindex{\def\PercentIndex{% \special@index{\quotechar\percentchar\actualchar\string\verb \quotechar*\verbatimchar\quotechar\bslash \percentchar\percentchar\verbatimchar}}} {\catcode`\%=12 \gdef\percentchar{%}} % \end{macrocode} % \end{macro} % \end{macro} % \subsection{Redefining the {\sf index} environment} %\changes{v1.4r}{89/04/22}{twocols env. placed into separate file} %\changes{v1.4?}{89/04/19}{use DEK's algorithm and implement % a twocols env.} %\changes{v1.4?}{89/04/16}{changes to the index env.} %\changes{v1.5a}{89/04/26}{Now input multicol.sty instead of % multcols.sty} % \begin{macro}{\ifhave@multicol} % \changes{v1.7a}{92/03/04}{Added to support avoiding multicol.sty} % By default % the index is set in three columns, and will start on the same % page as, and underneath, the last part of the text of the % documented style file, if possible. The last page will be % reformatted with balanced columns. This requires the {\sf % multicols} environment which is described elsewhere. % ^^A described elsewhere (see page~\xrefto{mittelbachmulti}). % So that {\sf doc} can be run independently of {\tt multicol.sty} % we first check for its existence and set the "have@multicol" flag % appropriately for use below. % \begin{macrocode} \newif\ifhave@multicol \openin\@ne multicol.sty \ifeof\@ne \else \have@multicoltrue \fi \closein\@ne \relax % \end{macrocode} % On systems where it is impossible to determine the existence of a % file using the above method the docstrip program can be directed % to force using multicol by including the next line. % \changes{v1.7i}{92/07/14}{Force use of multicol.sty if necessary.} % \begin{macrocode} %<+multicol>\have@multicoltrue % \end{macrocode} % \end{macro} % If we found {\tt multicol.sty} we use it. It would be nice to % delay this (and the re-definition of "theindex") until we knew % whether an index was actually required \ldots % \begin{macrocode} \ifhave@multicol \input{multicol.sty} \fi % \end{macrocode} % \begin{macro}{\IndexMin} % \begin{macro}{\c@IndexColumns} % \changes{v1.4t}{89/04/24}{Counter added.} % If {\tt multicol} is in use, % when the index is started we compute the remaining space on the % current page; if it is greater than \verb+\IndexMin+, the first % part of the index will then be placed in the available space. % The number of columns set is controlled by the counter % \verb+\c@IndexColumns+ which can be changed with a % \verb+\setcounter+ declaration. % \begin{macrocode} \newdimen\IndexMin \IndexMin = 80pt \newcount\c@IndexColumns \c@IndexColumns = 3 % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\theindex} % Now we start the multi-column mechanism, if appropriate. We use the % \verb+\c@IndexColumns+ \LaTeX{} counter declared above to denote % the number of columns and insert the `index prologue' text (which % might contain a \verb+\section+ call, etc.). See the default % definition for an example. % \changes{v1.4t}{89/04/24}{Incorporated new multicols env.} % \changes{v1.5a}{89/04/26}{Call multicols first} % \changes{v1.6e}{91/04/03}{Turned into env definition.} % \changes{v1.7a}{92/03/04}{Include test for multicols.} % \begin{macrocode} \ifhave@multicol \renewenvironment{theindex} {\begin{multicols}\c@IndexColumns[\index@prologue][\IndexMin]% % \end{macrocode} % Then we make a few last minute assignments to read the individual % index \verb+\item+$\,$s and finish off by ignoring any initial % space. % \begin{macrocode} \IndexParms \let\item\@idxitem \ignorespaces}% % \end{macrocode} % \end{macro} % \begin{macro}{\endtheindex} % \changes{v1.4t}{89/04/24}{Incorporated new multicols env.} % At the end of the index, we have only to end the {\sf multicols} % environment. % \begin{macrocode} {\end{multicols}} % \end{macrocode} % If we can't use {\sf multicols} we warn the user and use an % environment that's basically the one from {\tt article.sty}. % \begin{macrocode} \else \typeout{Can't find multicols.sty -- will use normal index layout if necessary.} \def\theindex{\@restonecoltrue\if@twocolumn\@restonecolfalse\fi \columnseprule \z@ \columnsep 35\p@ \twocolumn[\index@prologue]% \IndexParms \let\item\@idxitem \ignorespaces} \def\endtheindex{\if@restonecol\onecolumn\else\clearpage\fi} % \end{macrocode} % \end{macro} % Here are the necessary {\sf makeindex} declarations. We disable % scanning of macro names inside the index with "\scan@allowedfalse\n" % to avoid recursion. % \begin{macrocode} % %<+gind>preamble %<+gind>"\n \\begin{theindex} \n \\makeatletter\\scan@allowedfalse\n" %<+gind>postamble %<+gind>"\n\n \\end{theindex}\n" %<*style> % \end{macrocode} % \begin{macro}{\IndexPrologue} % \begin{macro}{\index@prologue} % The \verb+\IndexPrologue+ macro is used to place a short message % into the document above the index. It is implemented by % redefining \verb+\index@prologue+, a macro which holds the % default text. We'd better make it a \verb+\long+ macro to allow % \verb+\par+ commands in its argument. % \begin{macrocode} \long\def\IndexPrologue#1{\@bsphack\def\index@prologue{#1}\@esphack} % \end{macrocode} % Now we test whether the default is already defined by another % style file. If not we define it. % \begin{macrocode} \@ifundefined{index@prologue} {\def\index@prologue{\section*{Index}% \markboth{Index}{Index}% The italic numbers denote the pages where the corresponding entry is described, numbers underlined point to the definition, all others indicate the places where it is used. }}{} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\IndexParms} % These are some last-minute assignments for formatting the index % entries. They are defined in a separate macro so that a user can % substitute different definitions. We start by defining the % various parameters controlling leading and the separation between % the two columns. The entire index is set in \verb+\small+ size. % \begin{macrocode} \@ifundefined{IndexParms} {\def\IndexParms{% \parindent \z@ \columnsep 15pt \parskip 0pt plus 1pt \rightskip 15pt \mathsurround \z@ \parfillskip=-15pt \small % \end{macrocode} % \begin{macro}{\@idxitem} % \begin{macro}{\subitem} % \begin{macro}{\subsubitem} % Index items are formatted with hanging indentation for any items % which may require more than one line. % \begin{macrocode} \def\@idxitem{\par\hangindent 30pt}% % \end{macrocode} % Any sub-item in the index is formatted with a 15pt indentation % under its main heading. % \begin{macrocode} \def\subitem{\@idxitem\hspace*{15pt}}% % \end{macrocode} % Whilst sub-sub-items go in a further 10pt. % \begin{macrocode} \def\subsubitem{\@idxitem\hspace*{25pt}}% % \end{macrocode} % \begin{macro}{\indexspace} % The {\sf makeindex} program generates an \verb+\indexspace+ % before each new alphabetic section commences. After this final % definition we end the \verb+\@ifundefined+ and the definition of % \verb+\IndexParms+. % \begin{macrocode} \def\indexspace{\par\vspace{10pt plus 2pt minus 3pt}}% }}{} % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \end{macro} % \begin{macro}{\efill} % This definition of \verb+\efill+ is intended to be used after % index items which have no following text (for example, ``{\it % see\/}'' entries). It just ensures that the current line is % filled, preventing ``\verb+Underfull \hbox+'' messages. % \begin{macrocode} \def\efill{\hfill\nopagebreak}% % %<+gind|gglo>item_x1 "\\efill \n \\subitem " %<+gglo>item_x2 "\\ " %<+gind>item_x2 "\\efill \n \\subsubitem " %<*style> % \end{macrocode} % \end{macro} % \begin{macro}{\pfill} % \begin{macro}{\dotfil} % \begin{macro}{\dotfill} % The following definitions provide the \verb+\pfill+ command; if % this is specified in the index style file to {\sf makeindex} as % the delimiter to appear after index items, then the intervening % space before the referenced page numbers will be filled with % dots, with a little white space interpolated at each end of the % dots. If the line is broken the dots will show up on both lines. % \begin{macrocode} \def\dotfill{\leaders\hbox to.6em{\hss .\hss}\hskip\z@ plus 1fill}% \def\dotfil{\leaders\hbox to.6em{\hss .\hss}\hfil}% \def\pfill{\unskip~\dotfill\penalty500\strut\nobreak \dotfil~\ignorespaces}% % %<+gind|gglo>delim_0 "\\pfill " %<+gind|gglo>delim_1 "\\pfill " %<+gind|gglo>delim_2 "\\pfill " %<*style> % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \begin{macro}{\*} % Here is the definition for the \verb+\*+ macro. It isn't used in % this set of macros. % \begin{macrocode} \def\*{\leavevmode\lower.8ex\hbox{$\,\widetilde{\ }\,$}} % \end{macrocode} % \end{macro} % \begin{macro}{\main} % The {\it defining\/} entry for a macro name is flagged with the % string {\tt\encapchar main}\footnote{With the current definition % of {\tt\bslash encapchar} substituted for {\tt\encapchar}} in the % \verb+\index+ command; {\sf makeindex} processes this so that the % \verb+\main+ macro will be invoked to underline the page % number(s) on which the {\em definition\/} of the macro will be % found. % \begin{macrocode} \@ifundefined{main}{\def\main#1{\underline{#1}}}{} % \end{macrocode} % \end{macro} % \begin{macro}{\usage} % The \verb+\usage+ macro is used to indicate entries describing % the usage of a macro. The corresponding page number(s) will be % set in {\it italics}. % \begin{macrocode} \@ifundefined{usage}{\def\usage#1{{\it #1}}}{} % \end{macrocode} % \end{macro} % \begin{macro}{\PrintIndex} % \changes{v1.5k}{89/09/04}{`printindex changed to `PrintIndex.} % \changes{v1.7a}{92/02/26}{Documentation moved to interface section.} % \begin{macro}{\printindex} % This is the same as "\printindex" in the {\sf makeidx} style. % \begin{macrocode} \def\PrintIndex{\@input{\jobname.ind}} % \end{macrocode} % Since this macro was called \verb+\printindex+ in older versions % of {\tt doc.sty} we also provide the following definition. % \begin{macrocode} \def\printindex{\typeout{\string\printindex\space is obsolete!}% \typeout{Please use \string\PrintIndex\space if you are a macro implementor^^J or get a newer version of the documented software if you are a user}% \PrintIndex} % \end{macrocode} % \end{macro} % \end{macro} % We want headings in the index (and changes list) according to the % initial character of the next block of entries and have to instruct % {\sf makeindex} appropriately. Unfortunately the specification for % this changed sometime between versions 2.4 and 2.11 of {\sf % makeindex}. We provide both ways of doing it but unfortunately this % will always produce a warning message from {\sf makeindex}. This is % for older versions: % \changes{v1.7h}{92/07/01}{Turn off headings in gls file} % \begin{macrocode} % %<+gind,gglo>% The next lines will produce some warnings when %<+gind,gglo>% running Makeindex as they try to cover two different %<+gind,gglo>% versions of the program: %<+gind,gglo>lethead_prefix "{\\bf\\hfil " %<+gind,gglo>lethead_suffix "\\hfil}\\nopagebreak\n" %<+gind>lethead_flag 1 %<+gglo>lethead_flag 0 % \end{macrocode} % This works for newer ones: % \begin{macrocode} %<+gind,gglo>heading_prefix "{\\bf\\hfil " %<+gind,gglo>heading_suffix "\\hfil}\\nopagebreak\n" %<+gind>headings_flag 1 %<+gglo>headings_flag 0 %<*style> % \end{macrocode} % \subsection[Dealing with the change history] % {Dealing with the change history\footnotemark} % \footnotetext{The whole section was proposed by Brian {\sc Hamilton % Kelly}. He also documented and debugged the macros as % well as many other parts of this style option.} % To provide a change history log, the \verb+\changes+ command has % been introduced. This takes three arguments, respectively, the % version number of the file, the date of the change, and some detail % regarding what change has been made. The first of these arguments % is otherwise ignored, but the others are written out and may be used % to generate a history of changes, to be printed at the end of the % document. However, note that older versions of Chen's standard {\sf % makeindex} % program limit any textual field to just 64 characters; therefore, % is important that the number of characters in the second and third % parameters should not exceed 61 altogether (to allow for the % parentheses placed around the date). % \begin{macro}{\changes} % \changes{BHK}{89/04/26}{Documented {\tt\protect\bslash changes} % command.} % \changes{BHK}{89/04/26}{Changed definition of % {\tt\protect\bslash protect}.} % The output of % the \verb+\changes+ command goes into the \meta{Glossary\_File} % and therefore uses the normal \verb+\glossaryentry+ % commands.\footnote{Note that a recent change in \LaTeX{} 2.09 % changed the command name in the {\tt.glo} file from {\tt\bslash % indexentry} to {\tt\bslash glossaryentry}. It is therefore % necessary to have a special {\sf makeindex} style file called {\tt % gglo.ist} to process this file correctly.} Thus {\sf makeindex} % or a similar program can be used to process the output into a % sorted ``glossary''. The \verb+\changes+ command commences by % taking the usual measures to hide its spacing, and then redefines % \verb+\protect+ for use within the argument of the generated % \verb+\indexentry+ command. % We re-code nearly all chars found in \verb+\sanitize+ to letter % since the use of special style options which make some characters % active might upset the \verb+\changes+ command when writing its % entries to the file. However we have to leave \verb+%+ as comment % and \verb*+ + as \meta{space} otherwise chaos will happen. % And, of course the \verb+\+ should be available as escape % character. % \changes{v1.5v}{90/01/28}{`Re-code a lot of chars.} % \changes{v1.5m}{89/09/20}{`actualchar in second level removed.} % \changes{v1.5o}{89/09/24}{New sorting.} % \changes{v1.6c}{90/06/29}{Again new sorting.} % \begin{macrocode} \def\changes{\@bsphack\begingroup\@sanitize \catcode`\\\z@ \catcode`\ 10 \MakePercentIgnore \changes@} \def\changes@#1#2#3{% \def\protect##1{\string##1\space}% \edef\@tempa{\noexpand\glossary{#1\levelchar \expandafter\@gobble \saved@macroname\actualchar \string\verb\quotechar*% \verbatimchar\saved@macroname \verbatimchar:\levelchar #3}}% \@tempa\endgroup\@esphack} % \end{macrocode} % \begin{macro}{\saved@macroname} % \changes{BHK}{89/04/26}{Provided for sorting outside % {\sf macro} environment} % The entries are sorted for convenience by the name of the most % recently introduced macroname (i.e., that in the most recent % \verb+\begin{macro}+ command). We therefore provide % \verb+\saved@macroname+ to record that argument, and provide a % default definition in case \verb+\changes+ is used outside a {\sf % macro} environment. (This is a {\em wicked\/} hack to get such % entries at the beginning of the sorted list! It works providing no % macro names start with "!" or \verb+"+.) % \changes{v1.7a}{92/03/02}{Changed string used for better sorting.} % \begin{macrocode} \def\saved@macroname{"General"} % \end{macrocode} % \end{macro} % \begin{macro}{\RecordChanges} % \changes{BHK}{89/04/26}{Renames former {\tt\protect\bslash % PrintChanges} command.} % To cause the changes to be written (to a {\tt.glo}) file, we % define \verb+\RecordChanges+ to invoke \LaTeX's usual % \verb+\makeglossary+ command. % \begin{macrocode} \let\RecordChanges\makeglossary % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\GlossaryMin} % \changes{BHK}{89/04/26}{Added to support % {\tt\protect\bslash changes}.} % \begin{macro}{\c@GlossaryColumns} % \changes{BHK}{89/04/26}{Added to support % {\tt\protect\bslash changes}.} % The remaining macros are all analogues of those used for the {\sf % theindex} environment. When the glossary is started we compute % the space which remains at the bottom of the current page; if % this is greater than \verb+\GlossaryMin+ then the first part of % the glossary will be placed in the available space. The number % of columns set are controlled by the counter % \verb+\c@GlossaryColumns+ which can be changed with a % \verb+\setcounter+ declaration. % \begin{macrocode} \newdimen\GlossaryMin \GlossaryMin = 80pt \newcount\c@GlossaryColumns \c@GlossaryColumns = 2 % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\theglossary} % \changes{BHK}{89/04/26}{Added to support % {\tt\protect\bslash changes}.} % \changes{v1.5p}{89/09/28}{Now call `multicols first.} % \changes{v1.6e}{91/04/03}{Turned into env definition.} % \changes{v1.7a}{92/03/10}{Changed to work without multicols if % necessary.} % \begin{macro}{\endglossary} % \changes{BHK}{89/04/26}{Added to support % {\tt\protect\bslash changes}.} % The environment {\sf theglossary} is defined in the same manner % as the {\sf theindex} environment. % \begin{macrocode} \ifhave@multicol \newenvironment{theglossary}{% \begin{multicols}\c@GlossaryColumns [\glossary@prologue][\GlossaryMin]% \GlossaryParms \let\item\@idxitem \ignorespaces}% {\end{multicols}} \else \newenvironment{theglossary}{% \@restonecoltrue\if@twocolumn\@restonecolfalse\fi \columnseprule \z@ \columnsep 35\p@ \twocolumn[\glossary@prologue]% \GlossaryParms \let\item\@idxitem \ignorespaces} {\if@restonecol\onecolumn\else\clearpage\fi} % \end{macrocode} % \end{macro} % \end{macro} % Here are the necessary {\sf makeindex} declarations with scanning % disabled as for the index. % \begin{macrocode} % %<+gglo>preamble %<+gglo>"\n \\begin{theglossary} \n %<+gglo> \\makeatletter\\scan@allowedfalse\n" %<+gglo>postamble %<+gglo>"\n\n \\end{theglossary}\n" % \end{macrocode} % This difference from {\tt gind.ist} is necessary if you have an % up-to-date \LaTeX. % \begin{macrocode} %<+gglo>keyword "\\glossaryentry" %<*style> % \end{macrocode} % \begin{macro}{\GlossaryPrologue} % \changes{BHK}{89/04/26}{Added to support % {\tt\protect\bslash changes}.} % \begin{macro}{\glossary@prologue} % \changes{BHK}{89/04/26}{Added to support % {\tt\protect\bslash changes}.} % The \verb+\GlossaryPrologue+ macro is used to place a short % message above the glossary into the document. It is implemented % by redefining \verb+\glossary@prologue+, a macro which holds the % default text. We better make it a long macro to allow % \verb+\par+ commands in its argument. % \begin{macrocode} \long\def\GlossaryPrologue#1{\@bsphack \def\glossary@prologue{#1}% \@esphack} % \end{macrocode} % Now we test whether the default is already defined by another % style file. If not we define it. % \begin{macrocode} \@ifundefined{glossary@prologue} {\def\glossary@prologue{\section*{{Change History}}% \markboth{{Change History}}{{Change History}}% }}{} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\GlossaryParms} % \changes{BHK}{89/04/26}{Added to support % {\tt\protect\bslash changes}.} % Unless the user specifies otherwise, we set the change history % using the same parameters as for the index. % \begin{macrocode} \@ifundefined{GlossaryParms}{\let\GlossaryParms\IndexParms}{} % \end{macrocode} % \end{macro} % \begin{macro}{\PrintChanges} % \changes{BHK}{89/04/26}{Added to support % {\tt\protect\bslash changes}.} % To read in and print the sorted change history, just put the % \verb+\PrintChanges+ command as the last (commented-out, and thus % executed during the documentation pass through the file) command % in your style file. Alternatively, this command may form one of % the arguments of the \verb+\StopEventually+ command, although a % change history is probably {\em not\/} required if only the % description is being printed. % The command assumes that {\sf makeindex} or some other program % has processed the {\tt.glo} file to generate a sorted {\tt.gls} % file. % \begin{macrocode} \def\PrintChanges{\@input{\jobname.gls}} % \end{macrocode} % \end{macro} % % \subsection{Bells and whistles} % \begin{macro}{\StopEventually} % \changes{v1.5k}{89/09/04}{Support for checksum.} % \begin{macro}{\Finale} % \changes{v1.5k}{89/09/04}{Support for checksum.} % \changes{v1.5z}{90/04/22}{Define `Finale globally.} % \begin{macro}{\OnlyDescription} % Here is the default definition for \verb+\StopEventually+, we % simply save its argument in the macro \verb+\Finale+. % \begin{macrocode} \long\def\StopEventually#1{\@bsphack\gdef\Finale{#1% % \end{macrocode} % But \verb+\Finale+ will be called at the very end of a file. This % is exactly the point were we want to know if the file is % uncorrupted. Therefore we call \verb+\check@checksum+ at this % point. % \begin{macrocode} \check@checksum}% % \end{macrocode} % On the other hand: \verb+\StopEventually+ is more or less a % dividing point between description and code. So we start to look % for the check-sum of the documented file by calling % \verb+\init@checksum+. % \begin{macrocode} \init@checksum \@esphack} % \end{macrocode} % When the user places an \verb+\OnlyDescription+ declaration in % the driver file the document should only be typeset up to % \verb+\StopEventually+. We therefore have to redefine this macro. % \begin{macrocode} \def\OnlyDescription{\@bsphack\long\def\StopEventually##1{% % \end{macrocode} % In this case the argument of \verb+\StopEventually+ should be set % and afterwards \TeX{} should stop reading from this file. % Therefore we finish this macro with % \begin{macrocode} ##1\endinput}\@esphack} % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \begin{macro}{\meta} % \changes{v1.4t}{89/04/24}{Macro added.} % \begin{macro}{\m@ta} % \changes{v1.5w}{90/02/03}{Breaks at space allowed.} % \changes{v1.6a}{90/05/24}{Extra space bug corrected.} % The \verb+\meta+ macro is a bit tricky. We want to allow line % breaks at blanks in the argument but we don't want a break % in between. We therefore define \verb+\meta+ in a way that a % \verb*+ + is active when the argument is scanned. Words are then % scanned into \verb+\hbox+es. The active \verb*+ + will end the % preceding \verb+\hbox+ add an ordinary space and open a new % \verb+\hbox+. In this way breaks are only possible at spaces. It % would be even better to forbid page breaks but this is not % possible in an all cases. % \begin{macrocode} \begingroup \obeyspaces% \catcode`\^^M\active% % \end{macrocode} % We have to be careful to end all lines with a \verb+%+ sign in % this definition. % \begin{macrocode} \gdef\meta{\begingroup\obeyspaces\catcode`\^^M\active% \let^^M\do@space\let \do@space% % \end{macrocode} % To allow to break up words inside the \verb+\meta+ command we % redefine the \verb+\-+ command. It now has to end the last % open box, add a discretionary and start the next one for the % rest of the current word. See below for more details. % Finally we call \verb+\m@ta+ which % will scan the argument of \verb+\meta+. % \begin{macrocode} \def\-{\egroup\discretionary{-}{}{}\hbox\bgroup\it}% \m@ta}% \endgroup % \end{macrocode} % We start \verb+\m@ta+ by opening an \verb+\hbox+. % Inside this box there will be angle brackets and the argument % typeset in italic typeface. If there are no spaces or \verb+\-+ % commands in this argument the result will be a single box. But % when a space is encountered (which has \verb+\catcode+ 13) then % it will expand into \verb+\do@space+ which will close the current % box, output a space (so that we have a legitimate break point, and % then opens an new box to catch the rest of the argument. % \changes{v1.6d}{90/11/16}{`leavevmode added.} % \begin{macrocode} \def\m@ta#1{\leavevmode\hbox\bgroup$\langle$\it#1\/$\rangle$\egroup % \end{macrocode} % Finally, we have to close the group which was started in % \verb+\meta+ % to restore all our changes. % \begin{macrocode} \endgroup} % \end{macrocode} % The \verb+\do@space+ macro will produce the possible breakpoint % by ending the current box (\verb+\egroup+) and adding the % \verb+\space+ % into the surrounding paragraph. % \begin{macrocode} \def\do@space{\egroup\space % \end{macrocode} % Then we start a new box, switching again to italic to catch the % rest of the argument of \verb+\meta+. But we also have to make sure % that any space following directly will be ignored. Therefore we % check the following token and discard it as long as it is a token % with the meaning \verb+\do@space+, i.e.\ a $\verb*+ +_{13}$ or a % $\verb+^^M+_{13}$. % \begin{macrocode} \hbox\bgroup\it\futurelet\next\sp@ce} \def\sp@ce{\ifx\next\do@space\expandafter\sp@@ce\fi} \def\sp@@ce#1{\futurelet\next\sp@ce} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\IndexInput} % This next macro may be used to read in a separate file (possibly % a style file that is {\em not\/} documented by this means) and % set it verbatim, whilst scanning for macro names and indexing the % latter. This could be a useful first pass in preparing to % generate documentation for the file read. % \begin{macrocode} \def\IndexInput#1{% % \end{macrocode} % We commence by setting up a group, and initializing a % \verb+\trivlist+ as is normally done by a % \verb+\begin{macrocode}+ command. % \begin{macrocode} \begingroup \macro@code % \end{macrocode} % We also make spacing behave as in the {\sf macrocode} % environment, because otherwise all the spaces will be shown % explicitly. % \begin{macrocode} \frenchspacing \@vobeyspaces % \end{macrocode} % Then it only remains to read in the specified file, and finish % off the \verb+\trivlist+. % \changes{v1.5t}{89/11/07}{Call `endmacrocode instead of `endtrivlist.} % \begin{macrocode} \input{#1}\endmacrocode % \end{macrocode} % Of course, we need to finish off the group as well. % \begin{macrocode} \endgroup} % \end{macrocode} % \end{macro} % \begin{macro}{\maketitle} % The macro to generate titles is easily altered in order that it % can be used more than once (an article with many titles). In the % original, diverse macros were concealed after use with % \verb+\relax+. We must cancel anything that may have been put % into \verb+\@thanks+, etc., otherwise {\em all\/} titles will % carry forward any earlier such setting! % \changes{v1.5j}{89/06/09}{thispagestyle plain removed} % \begin{macrocode} \def\maketitle{\par \begingroup \def \thefootnote {\fnsymbol {footnote}}% \setcounter {footnote}\z@ \def \@makefnmark {\hbox to \z@{$^{\@thefnmark }$\hss }}% \if@twocolumn \twocolumn [\@maketitle ]% \else \newpage \global \@topnum \z@ \@maketitle \fi % \end{macrocode} % \changes{v1.5k}{89/09/04}{Added {\tt\protect\bslash ps@titlepage}} % For special formatting requirements (such as in TUGboat), we use % pagestyle \verb+titlepage+ for this; this is later defined to be % \verb+plain+, unless already defined, as, for example, by % \verb+ltugboat.sty+. % \begin{macrocode} \thispagestyle{titlepage}\@thanks \endgroup % \end{macrocode} % If the driver file documents many files, we don't want parts of a % title of one to propagate to the next, so we have to cancel % these: % \begin{macrocode} \setcounter {footnote}\z@ \gdef\@date{\today}\gdef\@thanks{}% \gdef\@author{}\gdef\@title{}} % \end{macrocode} % \end{macro} % \begin{macro}{\ps@titlepage} % \changes{v1.5k}{89/09/04}{Added {\tt\protect\bslash ps@titlepage}} % When a number of articles are concatenated into a journal, for % example, it is not usual for the title pages of such documents to % be formatted differently. Therefore, a style option such as {\sf % ltugboat} can define this macro in advance. However, if no such % definition exists, we use pagestyle {\tt plain} for title pages. % \begin{macrocode} \@ifundefined{ps@titlepage} {\let\ps@titlepage=\ps@plain}{} % \end{macrocode} % \end{macro} % \begin{macro}{\MakeShortVerb} % \changes{v1.7a}{92/02/27}{Added (from newdoc but now alters % `dospecials, `@sanitize).} % This arranges an abbreviation for "\verb" such that if you say % "\MakeShortVerb{\"\meta{c}"}" subsequently using % \meta{c}\meta{text}\meta{c} is equivalent to % "\verb"\meta{c}\meta{text}\meta{c}.\footnote{Warning: % the commentary in the rest of this section was written by Dave % Love.} In addition, the fact % that \meta{c} is made active is recorded for the benefit of the % {\sf verbatim} and {\sf macrocode} environments. % Note particularly that the definitions below are global. % The first thing we do (it needn't be first) is to record % the---presumably new---special character in "\dospecials" and % "\@sanitize" using "\add@special". % \begin{macrocode} \def\MakeShortVerb#1{% \typeout{*** Made \expandafter\@gobble\string#1\space a short reference for \string\verb \on@line\space ***}% \add@special{#1}% % \end{macrocode} % Then the character's current catcode is stored in "\cc\"\meta{c}. % \begin{macrocode} \expandafter \xdef\csname cc\string#1\endcsname{\the\catcode`#1}% % \end{macrocode} % The character is spliced into the definition using the same trick as % used in "\verb" (for instance), having activated "~" in a group. % \begin{macrocode} \begingroup \catcode`\~\active \lccode`\~`#1% \lowercase{% % \end{macrocode} % The character's old meaning is recorded in "\ac\"\meta{c} prior to % assigning it a new one. % \begin{macrocode} \global\expandafter\let \csname ac\string#1\endcsname~% \gdef~{\verb~}}% \endgroup % \end{macrocode} % Finally the character is made active. % \begin{macrocode} \global\catcode`#1\active} % \end{macrocode} % \end{macro} % \begin{macro}{\DeleteShortVerb} % \changes{v1.7a}{92/02/27}{Added (from newdoc but now alters % `dospecials, `@sanitize).} % Here's the means of undoing a "\MakeShortVerb", for instance in a % region where you need to use the character outside a verbatim % environment. It arranges for "\dospecials" and "\@sanitize" to be % altered appropriately, restores the saved catcode and, if necessary, % the character's meaning (as stored by % "\MakeShortVerb"). If the catcode wasn't stored in % "\cc\"\meta{c} (by "\MakeShortVerb") the command is silently % ignored. % \changes{v1.7a}{92/02/28}{Check for previous matched `MakeShortVerb % to avoid error.} % \begin{macrocode} \def\DeleteShortVerb#1{% \expandafter\ifx\csname cc\string#1\endcsname\relax \else \typeout{*** Deleted \expandafter\@gobble\string#1\space as short reference for \string\verb \on@line\space ***}% \rem@special{#1}% \global\catcode`#1\csname cc\string#1\endcsname \ifnum\catcode`#1=\active \begingroup \catcode`\~\active \lccode`\~`#1% \lowercase{% \global\expandafter\let\expandafter~% \csname ac\string#1\endcsname}% \endgroup \fi \fi} % \end{macrocode} % \end{macro} % \begin{macro}{\add@special} % \changes{v1.7a}{92/02/27}{Added for short verb facility.} % This helper macro adds its argument to the % "\dospecials" macro which is conventionally used by verbatim macros % to alter the catcodes of the currently active characters. We need % to add "\do\"\meta{c} to the expansion of "\dospecials" after % removing the character if it was already there to avoid multiple % copies building up should "\MakeShortVerb" not be balanced by % "\DeleteShortVerb" (in case anything that uses "\dospecials" cares % about repetitions). % \begin{macrocode} \def\add@special#1{% \rem@special{#1}% \expandafter\gdef\expandafter\dospecials\expandafter {\dospecials \do #1}% % \end{macrocode} % Similarly we have to add "\@makeother\"\meta{c} to "\@sanitize" % (which is used in things like "\index" to re-catcode all special % characters except braces). % \begin{macrocode} \expandafter\gdef\expandafter\@sanitize\expandafter {\@sanitize \@makeother #1}} % \end{macrocode} % \end{macro} % \begin{macro}{\rem@special} % \changes{v1.7a}{92/02/27}{Added for short verb facility.} % The inverse of "\add@special" is slightly trickier. "\do" is % re-defined to expand to nothing if its argument is the character of % interest, otherwise to expand simply to the argument. We can then % re-define "\dospecials" to be the expansion of itself. The space % after "=`##1" prevents an expansion to "\relax"! % \begin{macrocode} \def\rem@special#1{% \def\do##1{% \ifnum`#1=`##1 \else \noexpand\do\noexpand##1\fi}% \xdef\dospecials{\dospecials}% % \end{macrocode} % Fixing "\@sanitize" is the same except that we need to re-define % "\@makeother" which obviously needs to be done in a group. % \begin{macrocode} \begingroup \def\@makeother##1{% \ifnum`#1=`##1 \else \noexpand\@makeother\noexpand##1\fi}% \xdef\@sanitize{\@sanitize}% \endgroup} % \end{macrocode} % \end{macro} % \begin{macro}{\MakeShortverb} % \begin{macro}{\DeleteShortverb} % \changes{v1.7a}{92/02/27}{Added (from newdoc).} % These commands from {\sf newdoc} are now obsolete. % \begin{macrocode} \def\MakeShortverb{\typeout{*** Switch to \noexpand\MakeShortVerb syntax, this is obsolete ***}\MakeShortVerb} \def\DeleteShortverb{\typeout{*** Switch to \noexpand\DeleteShortVerb syntax, this is obsolete ***}\DeleteShortVerb} % \end{macrocode} % \end{macro} % \end{macro} % \subsection[Providing a checksum and character table] % {Providing a checksum and character table\footnotemark} % \footnotetext{Warning: the commentary in this section was % written by Dave Love. } % \begin{macro}{\init@checksum} % The checksum mechanism works by counting backslashes in the % macrocode. This initialises the count (when called from % "\StopEventually"). % \changes{v1.5k}{89/09/04}{Macro added to support checksum.} % \begin{macrocode} \def\init@checksum{\relax \global\bslash@cnt\z@} % \end{macrocode} % \end{macro} % \begin{macro}{\check@checksum} % \changes{v1.5k}{89/09/04}{Macro added to support checksum.} % This reports the sum compared with the value ("\bslash@cnt") the % file advertises. It's called from "\Finale" (if that hasn't been % re-defined). % \begin{macrocode} \def\check@checksum{\relax \ifnum\check@sum=\z@ \typeout{**********************************}% \typeout{* This macro file has no checksum!}% \typeout{* The checksum should be \the\bslash@cnt!}% \typeout{**********************************}% \else \ifnum\check@sum=\bslash@cnt \typeout{*******************}% \typeout{* Checksum passed *}% \typeout{*******************}% \else \errhelp\wrong@checksum \errmessage{Checksum not passed (\the\check@sum<>\the\bslash@cnt)}% \fi \fi \global\check@sum\z@} % \end{macrocode} % \end{macro} % \begin{macro}{\check@sum} % \changes{v1.5k}{89/09/04}{Macro added to support checksum.} % \begin{macro}{\bslash@cnt} % \changes{v1.5k}{89/09/04}{Macro added to support checksum.} % \begin{macro}{\wrong@checksum} % \changes{v1.5k}{89/09/04}{Macro added to support checksum.} % We need to define the counter for the number of backslashes counted % ("\bslash@cnt") and the value advertised by the file ("\check@sum") % as well as a help message for when things go wrong. % \begin{macrocode} \newcount\check@sum \check@sum = \z@ \newcount\bslash@cnt \bslash@cnt = \z@ \newhelp\wrong@checksum {The currently documented file seems to be wrong.^^J% Try to get a correct version.}% % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \begin{macro}{\CheckSum} % \changes{v1.5k}{89/09/04}{Macro added to support checksum.} % This is the interface to setting "\check@sum". % \begin{macrocode} \def\CheckSum#1{\@bsphack\global\check@sum#1\relax\@esphack} % \end{macrocode} % \end{macro} % \begin{macro}{\step@checksum} % \changes{v1.5k}{89/09/04}{Macro added to support checksum.} % This advances the count when a backslash is encountered in the % macrocode. % \begin{macrocode} \def\step@checksum{\global\advance\bslash@cnt\@ne} % \end{macrocode} % \end{macro} % \begin{macro}{\CharacterTable} % The user interface to the character table-checking does some % "\catcode"ing and then compares the following table with the % stored version. We need to have "@" of type ``other'' within the % table since this is the way it is usually returned when reading % in a normal document. To nevertheless have a private letter we % use "~" for this purpose. "~" does no harm as a ``letter'' as it % comes last in the table and therefore will not gobble following % space. % \changes{v1.5m}{89/09/20}{Macro added to check character translation % problems.} % \changes{v1.5q}{89/11/01}{Made character table more readable.} % \changes{v1.5t}{89/11/07}{Make \string\~{} letter in chartable % macros.} % \changes{v1.5u}{89/11/14}{Made @ other in default table.} % \begin{macrocode} \def\CharacterTable{\begingroup \CharTableChanges \character@table} % \end{macrocode} % \end{macro} % \def\MakePrivateLetters{\catcode`\~=11\makeatletter} % \begin{macro}{\character@table} % This does the work of comparing the tables and reporting the result. % Note that the following code is enclosed in a group % with "~" catcoded to letter. % \begin{macrocode} \begingroup \catcode`\~=11 \gdef\character@table#1{\def\used~table{#1}% \ifx\used~table\default~table \typeout{***************************}% \typeout{* Character table correct *}% \typeout{***************************}% \else \errhelp\wrong@table \errmessage{Character table corrupted}% \show\default~table \show\used~table \fi \endgroup} % \end{macrocode} % \end{macro} % \begin{macro}{\CharTableChanges} % When the character table is read in we need to scan it with a % fixed set of "\catcode"s. The reference table below was defined by % assuming the normal "\catcode"s of \TeX{}, i.e.\ "@" is of type % other and the only token of type ``letter'' are the usual letters % of the alphabet. If, for some reason, other characters are made % ``letters'' then their "\catcode"s need to be restored before % checking the table. Otherwise spaces in the table are gobbled and % we get the information that the tables are different, even if % they are actually equal. For this reason "\CharTableChanges" can % be set up to locally restore the "\catcode"s of such ``letters'' % to ``other''. % \begin{macrocode} \global\let\CharTableChanges\@empty % \end{macrocode} % \end{macro} % \begin{macro}{\default~table} % Here's what the table {\em should\/} look like (modulo spaces). % \begin{macrocode} \makeatother \gdef\default~table {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z Digits \0\1\2\3\4\5\6\7\8\9 Exclamation \! Double quote \" Hash (number) \# Dollar \$ Percent \% Ampersand \& Acute accent \' Left paren \( Right paren \) Asterisk \* Plus \+ Comma \, Minus \- Point \. Solidus \/ Colon \: Semicolon \; Less than \< Equals \= Greater than \> Question mark \? Commercial at \@ Left bracket \[ Backslash \\ Right bracket \] Circumflex \^ Underscore \_ Grave accent \` Left brace \{ Vertical bar \| Right brace \} Tilde \~} \endgroup % \end{macrocode} % \end{macro} % \let\MakePrivateLetters=\makeatletter % \begin{macro}{\wrong@table} % \changes{v1.7a}{92/02/28}{Moved to where the catcodes are right so it % works.} % We need a help message in case of problems. % \begin{macrocode} \newhelp\wrong@table{Some of the ASCII characters are corrupted.^^J I now \string\show\space you both tables for comparison.} % \end{macrocode} % \end{macro} % \subsection[Attaching line numbers to code lines] % {Attaching line numbers to code lines\footnotemark} % \footnotetext{Warning: the commentary was written by Dave % Love.} % The code in this section allows index entries to refer to code line % numbers---the number of the first line of macrocode in the {\sf macro} % environment. % \begin{macro}{\codeline@index} % Indexing by code line is controlled by the "codeline@index" switch. % \changes{v1.5s}{89/11/05}{Support for code line no. (Undoc)} % \changes{v1.7a}{92/02/24}{Documented code line no. support.} % \begin{macrocode} \newif\ifcodeline@index \codeline@indexfalse % \end{macrocode} % \end{macro} % \begin{macro}{\codeline@wrindex} % The code index entries are written out by "\special@index". If % indexing is by code line this is "\let" to "\codeline@wrindex"; % if indexing is by page it is just "\index". However, if % "\nofiles" is given, we omit writing such an index entry at all. % \changes{v1.7j}{92/08/14}{Added `if@filesw.} % \begin{macrocode} \def\codeline@wrindex#1{\if@filesw \immediate\write\@indexfile {\string\indexentry{#1}% {\number\c@CodelineNo}}\fi} % \end{macrocode} % \end{macro} % \begin{macro}{\special@index} % By default no index entries are written out. % \begin{macrocode} \let\special@index = \@gobble % \end{macrocode} % \end{macro} % \begin{macro}{\CodelineIndex} % \changes{v1.5u}{89/11/14}{Added `PageIndex and `CodelineIndex (Undoc)} % This switches on use of the index file with "\makeindex", sets the % switch to indicate code line numbering and defines "\special@index" % appropriately. % \begin{macrocode} \def\CodelineIndex{\makeindex \codeline@indextrue \let\special@index\codeline@wrindex} % \end{macrocode} % \end{macro} % \begin{macro}{\PageIndex} % "\PageIndex" is similar. % \begin{macrocode} \def\PageIndex{\makeindex \codeline@indexfalse \let\special@index\index} % \end{macrocode} % \end{macro} % \begin{macro}{\c@CodelineNo} % \changes{v1.5l}{89/09/10}{Counter added to support code line numbers.} % \changes{v1.5y}{90/02/24}{Default changed.} % \changes{v1.6b}{90/06/15}{`rm moved before `scriptsize to % avoid unnecessary fontwarning.} % We need a counter to keep track of the line number. % \begin{macrocode} \newcount\c@CodelineNo \c@CodelineNo\z@ % \end{macrocode} % \end{macro} % \begin{macro}{\theCodelineNo} % \changes{v1.7a}{92/02/25}{Existing definition not overwritten.} % \changes{v1.7a}{92/03/12}{Use `reset@font for NFSS.} % This provides a hook to control the format of line numbers which may % be defined in a style file. % \begin{macrocode} \@ifundefined{theCodelineNo} {\ifx\selectfont\undefined \def\theCodelineNo{\rm\scriptsize\arabic{CodelineNo}}% \else \def\theCodelineNo{\reset@font\scriptsize\arabic{CodelineNo}}% \fi} {} % \end{macrocode} % \end{macro} % \subsection{Layout Parameters for documenting style files} % \begin{macro}{\tolerance} % People documenting style files would probably rather have things % ``sticking out'' in overfull \verb+\hbox+es and poorish spacing, % because they probably don't want to spend a lot of time on making % all the line breaks perfect! % \begin{macrocode} \tolerance=1000\relax % \end{macrocode} % \end{macro} % \DeleteShortVerb{\"} % The following \verb+\mathcode+ definitions allow the characters % `\verb+\+' % and `{\tt @}' to appear in \verb+\tt+ font when invoked in math % mode;\footnote{You may wonder why the definitions state that both % characters belong to the {\em variable family\/} % (i.e.\ the number 7 in front). The reason is this: % Originally the {\tt\bslash mathcode} of % {\tt\bslash} was defined to be {\tt "075C}, % i.e.\ ordinary character number 92 (hex 5C) in % math family number 7 which is the typewriter family in % standard \LaTeX. % But this file should not depend on this specific % setting, so I changed these {\tt\bslash mathcode}$\,$s % to work with any family assignments. For an example % see the article about the new font selection scheme.} % particularly for something like $\verb+\@abc+=1$. % If an {\em old\/} version of the {\sf german} style option is in % force, then the `\verb+"+' character is active and would upset the % definition of the \meta{16-bit number} quantities below, therefore % we change the \verb+\catcode+ of \verb+"+ inside a group, and use % \verb+\global+. % \begin{macrocode} { \catcode`\"=12 \global\mathcode`\\="705C \global\mathcode`\@="7040 } % \end{macrocode} % \MakeShortVerb{\"} % \begin{macro}{\DocstyleParms} % This macro can be used, for example, to assign new values to % \verb+\MacrocodeTopsep+ and \verb+\MacroIndent+ and some other % internal registers. If it is already defined, the default % definition won't be carried out. Note that it is necessary to % assign new values via this macro if it should be done in a style % file (like {\tt ltugboat.sty} for example) since the registers are % undefined before {\tt doc.sty} is read in. The default values % for the internal registers are scattered over this file. % \changes{v1.5u}{89/11/14}{`DocStyleParms now empty} % \begin{macrocode} \@ifundefined{DocstyleParms}{}{} % \end{macrocode} % Now we allow overwriting the values by calling % \verb+\DocstyleParms+. % \begin{macrocode} \DocstyleParms \let\DocstyleParms\relax % \end{macrocode} % \end{macro} % \begin{macro}{\AmSTeX} % \changes{v1.5j}{89/06/09}{Macro AmsTeX renamed to AmSTeX} % \begin{macro}{\BibTeX} % \begin{macro}{\SliTeX} % Here are a few definitions which can usefully be employed when % documenting style files: now we can readily refer to \AmSTeX, % \BibTeX\ and \SliTeX, as well as the usual \TeX\ and \LaTeX. % \begin{macrocode} \@ifundefined{AmSTeX} {\def\AmSTeX{\leavevmode\hbox{$\cal A\kern-.2em\lower.376ex% \hbox{$\cal M$}\kern-.2em\cal S$-\TeX}}}{} \@ifundefined{BibTeX} {\def\BibTeX{{\rm B\kern-.05em{\sc i\kern-.025em b}\kern-.08em% T\kern-.1667em\lower.7ex\hbox{E}\kern-.125emX}}}{} \@ifundefined{SliTeX} {\def\SliTeX{{\rm S\kern-.06emL\kern-.18em\raise.32ex\hbox {\sc i}\kern -.03em\TeX}}}{} % \end{macrocode} % \end{macro} % \end{macro} % \end{macro} % \begin{macro}{\PlainTeX} % \changes{v1.5g}{89/05/07}{space between plain and TeX changed.} % \begin{macro}{\Web} % There's even a \PlainTeX{} and a \Web. % \begin{macrocode} \@ifundefined{PlainTeX}{\def\PlainTeX{{\sc Plain}\kern2pt\TeX}}{} \@ifundefined{Web}{\def\Web{{\sc Web}}}{} % \end{macrocode} % \end{macro} % \end{macro} % \subsection{Changing the {\tt\protect\bslash catcode} of \%} % \begin{macro}{\MakePercentIgnore} % \begin{macro}{\MakePercentComment} % And finally the most important bit: we change the \verb+\catcode+ % of `\verb+%+' so that it is ignored (which is how we are able to % produce this document!). We provide two commands to do the actual % switching. %^^A The \verb+\MakePercentIgnore+ is then called as the %^^A last command in this file. % \begin{macrocode} \def\MakePercentIgnore{\catcode`\%9\relax} \def\MakePercentComment{\catcode`\%14\relax} % \end{macrocode} % \end{macro} % \end{macro} % \begin{macro}{\DocInput} % The two macros above are now used to define the % \verb+\DocInput+ macro which was introduced in version v1.5l % (or so) of % the {\tt doc} style option. In older versions % \verb+\MakePercentIgnore+ was placed at the very end of {\tt % doc.sty}. % \begin{macrocode} \def\DocInput#1{\MakePercentIgnore\input{#1}\MakePercentComment} % \end{macrocode} % \end{macro} % We can now finish the {\tt docstrip} main module. % \begin{macrocode} % % \end{macrocode} % \begin{macro}{\on@line} % Finally something for people with an old \LaTeX: % \changes{v1.7k}{92/08/24}{Macro and test added.} % \begin{macrocode} \ifx\on@line\undefined \def\on@line{ on input line \the\inputlineno} \errhelp{Support for input line numbers has been added to latex.tex .^^J^^J% Please update to a newer LaTeX release.} \errmessage{Obsolete LaTeX release (older than Dec.91)} % \end{macrocode} % \end{macro} % \Finale % \PrintIndex \PrintChanges \endinput